mark-twin 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70005ba12f4a11cde04a57fd68615d3478d2ca974f2aaa6eb49d650c2201a9ac
-  data.tar.gz: c0e5e45e52cdb20c5758ce11c0b81fdc20b309a1cc9c637a146833b001424e05
+  metadata.gz: 39f52a8341611b4a17bbeaffae64e21e7ffc2123f1b766df494eb422db697cb6
+  data.tar.gz: 224e40d39832efc3542c1c3de00e4c6fe30d01c72ca4f84ff5bc9868f15cedd3
 SHA512:
-  metadata.gz: 05ae1ff58350d3fcde9d3ac959859f474c585d1e9a11ce5141a36093aa77d597362529c33bc17b4774b7eb7aecf1330c70baf84392a6de081b2fab3ee7c918cc
-  data.tar.gz: 7a730c9622eaaf684b5f4805fb93a19d84a53344b415eec873ab14701ae3a6b77515a2806437e333b408db4a742397390b1f02bc7c4ad6791585ac480e27e1b7
+  metadata.gz: 8f217e753b18810cad48b2e6c2f3360a3cc84e4f6449dd14f9f62aae4243b55d44a4d2b8321a8f60228c4ca696e97106f9cdca1e6a54f404436af284130609dd
+  data.tar.gz: 301088d4bd68082461e9e8d0730d1c921336256e8fe3f3a755f918c6e189fc4238fc4bd7c3f7e4e8879474f9736ef4272a5117ce8b3b97316983031e0656201b

data/ARCHITECTURE.md

@@ -9,14 +9,17 @@ sync-files (.md)
    grubber          parse Markdown, extract YAML blocks, merge frontmatter
       │
       ▼
+   Template         substitute {{tokens}} in record fields (no-op without hosts)
+      │
+      ▼
    Scanner          load_jobs → list[Job] → group(jobs) → list[Program]
       │
-      ├──▶  CLI       list / status / sync
+      ├──▶  CLI       list / status / sync / doctor
       │
       └──▶  Picker    fzf + apex preview, returns selected Program
                           │
                           ▼
-                       Sync   rsync per Job, mount check, Cmd hook
+                       Sync   rsync (or render) per Job, mount check, Cmd hook
 ```
 
 ## Package layout
@@ -24,9 +27,10 @@ sync-files (.md)
 ```
 lib/twin/
   version.rb
-  config.rb     ~/.config/twin/config.yaml loader
-  scanner.rb    Job, Program structs; grubber + stat → grouped Programs
-  sync.rb       rsync execution, mount check, post-sync hook
+  template.rb   {{token}} substitution + render-file helper
+  config.rb     ~/.config/twin/config.yaml loader; host table → var_map
+  scanner.rb    Job, Program structs; grubber + template + stat → grouped Programs
+  sync.rb       rsync / render execution, mount check, post-sync hook
   picker.rb     fzf wrapper with apex preview
   cli.rb        subcommand dispatcher
 
@@ -39,12 +43,15 @@ test/test_pure.rb
 **Job** — one YAML block:
 
 ```
-program, path, description, active, excludes, label, source, target, cmd, sync_file,
+program, path, description, active, excludes, label, source, target, cmd,
+delete, render, render_outdated, target_path_field, sync_file,
 source_exists, target_exists, source_mtime, target_mtime, conflict
 ```
 
 `Job#status` → one of `disabled / both_missing / missing_source / missing_target /
-target_newer / in_sync / source_newer`.
+target_newer / in_sync / source_newer`. Render jobs derive status from content
+(`render_outdated`), not mtime; non-render jobs ignore those fields.
+`Job#target_path` joins `target` with `target_path_field || path`.
 
 **Program** — group of Jobs sharing a `program` name:
 
@@ -64,9 +71,20 @@ sync_dir: /path/to/sync-files
 global_excludes: [".DS_Store", ".git/"]
 apex_theme: ralf
 apex_width: 80
+
+host: mini          # which host twin runs as
+target: book        # default sync target
+hosts:
+  mini: { home: /Volumes/lightning/users/extern, git: /Volumes/lightning/Git }
+  book: { home: /Users/ralf, git: /Users/ralf/git, mount: /Volumes/ralf }
 ```
 
-Environment overrides: `TWIN_SYNC_DIR` (sync_dir), `TWIN_CONFIG` (config path).
+`Config#var_map` flattens the host table for the (`host` → `target`) pair into
+`{ "src.home" => …, "dst.home" => …, "dst.mount" => … }` — empty when no hosts
+are configured (templating inert). See the **Templating** section.
+
+Environment overrides: `TWIN_SYNC_DIR` (sync_dir), `TWIN_CONFIG` (config path),
+`TWIN_HOST` (host).
 
 ## Sync-files
 
@@ -77,6 +95,32 @@ record is self-contained.
 Multiple blocks may share the same `Program` value — these are treated as
 one logical unit by twin.
 
+## Templating
+
+Substitution sits between grubber and `build_job`, so grubber never sees
+`{{tokens}}` and stays untouched. `Scanner.load_jobs` calls
+`Template.substitute_record` on each record's path-bearing fields (`Source`,
+`Target`, `Path`, `Target-Path`, `Exclude`, `Cmd`) using `cfg.var_map`. This
+*must* run before `build_job`, which immediately `stat`s the resolved paths.
+Unknown `{{token}}` → hard error (never sync a half-rendered path).
+
+Three namespaces, one fixed meaning each:
+
+- `{{src.*}}` — the running host's own paths (read side, `Source:`).
+- `{{dst.mount}}` — where the target is mounted here (write side, `Target:`).
+- `{{dst.*}}` — the target's native paths, used in **rendered file content**.
+
+The mount/native split is the crux: a file written to `/Volumes/ralf/…` but read
+by the target machine must contain `/Users/ralf/…`. Path fields and file content
+draw from different namespaces, so a token never means two things.
+
+`{{` opens a YAML flow mapping, so templated values must be quoted in the
+sync-file (`Source: "{{src.home}}"`) — as in Ansible. Without a `hosts` table
+`var_map` is empty and substitution is a no-op.
+
+See [docs/templating-design.md](docs/templating-design.md) for the full
+rationale.
+
 ## Picker
 
 Two stages:
@@ -107,6 +151,11 @@ File argument resolution (`twin <arg>` and `--file=<arg>`):
 Unknown options (anything starting with `-` that isn't `--help`) print an
 error pointing at `twin --help` and exit 1.
 
+`twin doctor` checks required tools (grubber, rsync, fzf), optional renderers
+(apex, glow, bat), templating (host/target resolve, every `{{token}}` resolves),
+and whether all configured sync targets are mounted. Exits 1 if any required
+check fails.
+
 ## Sync
 
 Before syncing:
@@ -116,14 +165,33 @@ Before syncing:
 2. **Conflict warning** — emits stderr listing jobs where the target is
    newer than the source. Continues anyway (`rsync --update` skips them).
 
-Then per Job:
+Then per Job, **rsync path** (non-render):
 
 ```
-rsync -av --update [--exclude=...]* src/ tgt/
+rsync -av --itemize-changes --update [--delete] [--exclude=...]* src/ tgt/
 ```
 
-If `Cmd` is set on the block and not in dry-run mode, the command is
-executed via `sh -c` after a successful rsync.
+`--delete` is added when the Job has `delete: true` (from `Delete: true`).
+`--itemize-changes` makes change detection deterministic: `Sync.transferred?`
+matches itemize lines (`/\A[<>ch*][fdLDS]/` — `>f…`, `cd…`, `*deleting`),
+covering files, directories and deletions, with no scraping of rsync's prose.
+
+If `Cmd` is set, it runs via `sh -c` after rsync — but only when something was
+actually transferred. No-op syncs (target up to date, or target newer and
+skipped by `--update`) leave the hook silent. On failure the exit code is
+included in the output and the job is marked failed.
+
+When a job has a known conflict (`target_newer`) and nothing transferred, the
+output notes `"skipped: target is newer, source not synced"`.
+
+**Render path** (`render: true`) — `Sync.render_job`. Templates can't be
+rsync'd byte-for-byte, so instead: read source, substitute `{{dst.*}}` in the
+content, compare against the current target bytes, write only if they differ.
+`changed` drives the same `Cmd` gate. Content-hash comparison (not mtime)
+sidesteps the `--update` trap — a freshly rendered temp is always "newer".
+Render is file-only; a directory source is an error. `twin status` mirrors this:
+render-job status comes from the same content comparison (`render_outdated`),
+so a stale target with a matching mtime is still flagged `source_newer`.
 
 ## External dependencies
 

data/README.md

@@ -119,6 +119,7 @@ twin status                  # listing with source/target mtimes
 twin sync -p grubber         # sync one program by name pattern
 twin sync --file=repos       # sync all programs from a sync-file
 twin sync --dry-run          # preview without writing
+twin doctor                  # check tools, renderers, and sync targets
 twin --help                  # show usage
 ```
 
@@ -145,7 +146,8 @@ global_excludes:
 # apex_code_highlight_theme: dark
 ```
 
-Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`.
+Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`, `TWIN_HOST` (which host
+twin runs as — lets one config serve both machines).
 
 ## Sync-files
 
@@ -181,12 +183,74 @@ Frontmatter fields (`Active`, `Label`, `Source`, `Target`) are merged into
 every block by grubber. Multiple blocks can share the same `Program` — twin
 groups them and treats the program as the unit of selection.
 
-The optional `Cmd` field is where the hidden trick happens: after a
-successful sync, twin runs an arbitrary shell command — typically a `curl`
-to a local automation endpoint like [mi.lan](https://github.com/rhsev/mi.lan) —
-to reload the program, run an installer, restart a service, or notify
-another machine. One config sync, one config *deployed*. See the Helix
-entry in [examples/home.md](examples/home.md).
+The optional `Cmd` field runs an arbitrary shell command after a successful
+sync — typically a `curl` to a local automation endpoint like
+[mi.lan](https://github.com/rhsev/mi.lan) to reload a program, restart a
+service, or notify another machine. The command only runs when rsync actually
+transferred bytes; no-op syncs skip it. See the Helix entry in
+[examples/home.md](examples/home.md).
+
+The optional `Delete: true` field adds `--delete` to the rsync invocation,
+so files removed from the source are also removed on the target. Useful for
+directory syncs where the target should mirror the source exactly.
+
+## Templating
+
+Some configs differ per machine — a LaunchAgent plist that points at
+`/Volumes/lightning/…` on one Mac and `/Users/ralf/…` on another, a
+`settings.json` with a device-specific id. Those used to fall out of twin and
+get hand-maintained. Templating folds them back into one source of truth.
+
+Define a host table in `~/.config/twin/config.yaml`:
+
+```yaml
+host: mini          # which machine twin runs on
+target: book        # the machine being synced to
+
+hosts:
+  mini: { home: /Volumes/lightning/users/extern, git: /Volumes/lightning/Git }
+  book: { home: /Users/ralf, git: /Users/ralf/git, mount: /Volumes/ralf }
+```
+
+That exposes three sets of `{{tokens}}`, each with one fixed meaning:
+
+| Token | Resolves to | Use in |
+|---|---|---|
+| `{{src.home}}`, `{{src.git}}`, … | the running host's own paths | `Source:` (read side) |
+| `{{dst.mount}}` | where the target is mounted here (`/Volumes/ralf`) | `Target:` (write side) |
+| `{{dst.home}}`, `{{dst.git}}`, … | the target's *native* paths | rendered file **content** |
+
+The distinction matters: a file *written* to the mount (`/Volumes/ralf/…`) but
+*read* by the target machine must contain that machine's native paths
+(`/Users/ralf/…`). `{{dst.mount}}` and `{{dst.home}}` keep the two apart.
+
+> **Quote templated values.** `{{` at the start of a YAML value collides with
+> YAML flow-mapping syntax, so write `Source: "{{src.home}}"`, not
+> `Source: {{src.home}}` — exactly as in Ansible.
+
+`Render: true` turns a block from copy into *render*: twin reads the source as a
+template, substitutes `{{…}}` in its **content**, and writes the result only if
+it differs from the current target (so a `Cmd` hook fires only on a real change).
+`Target-Path:` overrides the target-side relative path when it differs from the
+source layout:
+
+````markdown
+## LiveSync LaunchAgent
+
+```yaml
+Program: livesync-agent
+Source: "{{src.home}}/Automation/launchd"
+Path: com.ralf.livesync.plist
+Target: "{{dst.mount}}"
+Target-Path: Library/LaunchAgents/com.ralf.livesync.plist
+Render: true
+Cmd: curl -s http://mi.lan/livesync-reload
+```
+````
+
+`twin doctor` checks that every `{{token}}` across your sync-files resolves, and
+`twin status` compares rendered output by content (not mtime). Without a `hosts`
+table, templating is inert and literal-path sync-files behave exactly as before.
 
 ## Design
 

data/lib/twin/cli.rb

@@ -1,6 +1,7 @@
 require "optparse"
 require "json"
 require "set"
+require "time"  # Time#iso8601 for --json output
 
 require_relative "config"
 require_relative "scanner"
@@ -21,6 +22,7 @@ module Twin
         twin list   [--all] [--label X] [--file X] [--json]
         twin status [--all] [--label X] [--file X] [--json]
         twin sync   [-p PATTERN] [--label X] [--file X] [--all] [--dry-run]
+        twin doctor                check tools, renderers, and sync targets
         twin --help                show this message
 
       FILE ARGUMENT:
@@ -44,6 +46,7 @@ module Twin
       when "list"     then cmd_list(cfg, argv.drop(1))
       when "status"   then cmd_status(cfg, argv.drop(1))
       when "sync"     then cmd_sync(cfg, argv.drop(1))
+      when "doctor"   then cmd_doctor(cfg)
       when "-h", "--help", "help"
         puts USAGE
       when /\A-/
@@ -188,13 +191,88 @@ module Twin
 
       puts "→ #{program.name}"
       jobs.each do |job|
-        success, output = Twin::Sync.run_job(cfg, job, dry_run: dry_run)
+        success, output, = Twin::Sync.run_job(cfg, job, dry_run: dry_run)
         puts "  • #{job.path}"
         puts output.gsub(/^/, "    ") if output && !output.strip.empty?
         warn "  error syncing #{job.path}" unless success
       end
     end
 
+    # ── doctor ─────────────────────────────────────────────────────────────────
+
+    def cmd_doctor(cfg)
+      ok = true
+
+      puts "Tools"
+      %w[grubber rsync fzf].each do |bin|
+        if tool_available?(bin)
+          puts "  ✓  #{bin}"
+        else
+          puts "  ✗  #{bin}  (required — not found in PATH)"
+          ok = false
+        end
+      end
+
+      puts "\nRenderers (preview)"
+      found_renderer = false
+      %w[apex glow bat].each do |bin|
+        if tool_available?(bin)
+          puts "  ✓  #{bin}"
+          found_renderer = true
+        else
+          puts "  –  #{bin}  (not installed)"
+        end
+      end
+      puts "  ⚠   no renderer found — file preview will fall back to cat" unless found_renderer
+
+      puts "\nTemplating"
+      if cfg.hosts.empty?
+        puts "  –  no hosts configured"
+      else
+        %i[host target].each do |attr|
+          name = cfg.send(attr)
+          if name.empty?
+            puts "  ✗  #{attr} not set in config"
+            ok = false
+          elsif cfg.hosts.key?(name)
+            puts "  ✓  #{attr}: #{name}"
+          else
+            puts "  ✗  #{attr} #{name.inspect} not found in hosts"
+            ok = false
+          end
+        end
+      end
+
+      puts "\nTargets"
+      begin
+        programs = Scanner.load_programs(cfg, show_all: true)
+        puts "  ✓  all template tokens resolved" unless cfg.hosts.empty?
+        targets  = programs.flat_map(&:jobs).map(&:target).uniq.sort
+        if targets.empty?
+          puts "  (no programs loaded)"
+        else
+          targets.each do |tgt|
+            if Twin::Sync.mounted?(tgt)
+              puts "  ✓  #{tgt}"
+            else
+              puts "  ✗  #{tgt}  (not mounted)"
+              ok = false
+            end
+          end
+        end
+      rescue => e
+        puts "  ✗  #{e.message}"
+        ok = false
+      end
+
+      puts ok ? "\nAll checks passed." : "\nSome checks failed."
+      exit 1 unless ok
+    end
+
+    def tool_available?(name)
+      system("command -v #{name} > /dev/null 2>&1")
+    end
+
     # ── option parsing ─────────────────────────────────────────────────────────
 
     def parse_filter_opts(args)

data/lib/twin/config.rb

@@ -5,7 +5,8 @@ module Twin
   class Config
     attr_accessor :sync_dir, :global_excludes,
                   :apex_theme, :apex_width,
-                  :apex_code_highlight, :apex_code_highlight_theme
+                  :apex_code_highlight, :apex_code_highlight_theme,
+                  :hosts, :host, :target
 
     DEFAULTS = {
       "global_excludes"           => [".DS_Store"],
@@ -13,6 +14,9 @@ module Twin
       "apex_width"                => nil,
       "apex_code_highlight"       => nil,
       "apex_code_highlight_theme" => nil,
+      "hosts"                     => {},
+      "host"                      => "",
+      "target"                    => "",
     }.freeze
 
     def initialize(data = {})
@@ -23,6 +27,27 @@ module Twin
       @apex_width                = merged["apex_width"]
       @apex_code_highlight       = merged["apex_code_highlight"]
       @apex_code_highlight_theme = merged["apex_code_highlight_theme"]
+      @hosts                     = merged["hosts"] || {}
+      @host                      = ENV["TWIN_HOST"] || merged["host"].to_s
+      @target                    = merged["target"].to_s
+    end
+
+    # Build the flat substitution map {src.home => ..., dst.home => ..., dst.mount => ...}.
+    # Returns empty hash when no hosts are configured (substitution becomes a no-op).
+    def var_map
+      return {} if hosts.empty?
+      raise "host not set in config"   if host.empty?
+      raise "target not set in config" if target.empty?
+
+      src_host = hosts[host]
+      dst_host = hosts[target]
+      raise "unknown host #{host.inspect} (not in hosts)"     unless src_host
+      raise "unknown target #{target.inspect} (not in hosts)" unless dst_host
+
+      map = {}
+      src_host.each { |k, v| map["src.#{k}"] = v.to_s }
+      dst_host.each { |k, v| map["dst.#{k}"] = v.to_s }
+      map
     end
 
     def self.load

data/lib/twin/scanner.rb

@@ -5,18 +5,21 @@ module Twin
   # One YAML block from a sync-file, enriched with live filesystem state.
   Job = Struct.new(
     :program, :path, :description, :active, :excludes, :label,
-    :source, :target, :cmd, :sync_file,
+    :source, :target, :cmd, :delete, :render, :render_outdated, :target_path_field, :sync_file,
     :source_exists, :target_exists, :source_mtime, :target_mtime, :conflict,
     keyword_init: true,
   ) do
     def source_path = File.join(source, path)
-    def target_path = File.join(target, path)
+    def target_path = File.join(target, target_path_field || path)
 
     def status
       return :disabled if active != 1
       return :both_missing if !source_exists && !target_exists
       return :missing_source unless source_exists
       return :missing_target unless target_exists
+      # Render jobs compare by content, not mtime — a rendered target's mtime
+      # bears no relation to the template's.
+      return render_outdated ? :source_newer : :in_sync if render
       return :target_newer if conflict
       return :in_sync if source_mtime.nil? || target_mtime.nil?
       delta = source_mtime - target_mtime
@@ -65,7 +68,11 @@ module Twin
       rescue JSON::ParserError => e
         raise "grubber returned invalid JSON: #{e.message}"
       end
-      records.filter_map { |r| build_job(r) }
+      vars = cfg.var_map
+      records.filter_map do |r|
+        context = "#{r["Program"]} in #{File.basename(r["_note_file"].to_s)}"
+        build_job(Twin::Template.substitute_record(r, vars, context: context), vars)
+      end
     end
 
     def load_programs(cfg, file: nil, label: nil, show_all: false)
@@ -98,38 +105,49 @@ module Twin
           .map { |(name, _file), js| Program.new(name: name, jobs: js) }
     end
 
-    def build_job(r)
-      path   = r["Path"].to_s
-      source = r["Source"].to_s
-      target = r["Target"].to_s
+    def build_job(r, vars = {})
+      path              = r["Path"].to_s
+      source            = r["Source"].to_s
+      target            = r["Target"].to_s
+      target_path_field = r["Target-Path"].then { |v| v.to_s.empty? ? nil : v.to_s }
       return nil if path.empty? || source.empty? || target.empty?
 
+      render   = r["Render"] == true
       excludes = (r["Exclude"] || "").split(",").map(&:strip).reject(&:empty?)
 
       src_full = File.join(source, path)
-      tgt_full = File.join(target, path)
+      tgt_full = File.join(target, target_path_field || path)
       src_exists, src_mtime = stat(src_full)
       tgt_exists, tgt_mtime = stat(tgt_full)
+
+      # Render jobs: status is content-based (mtime is meaningless for a rendered
+      # target). conflict stays false so the mtime conflict-warning skips them.
+      render_outdated = render ? render_outdated?(src_full, tgt_full, vars, path) : nil
+
       # Same 60s tolerance as Job#status, so mtime jitter never flags a conflict.
-      conflict = src_exists && tgt_exists && tgt_mtime && src_mtime &&
+      conflict = !render && src_exists && tgt_exists && tgt_mtime && src_mtime &&
                  tgt_mtime - src_mtime >= 60
 
       Job.new(
-        program:       r["Program"].to_s,
-        path:          path,
-        description:   r["Description"].to_s,
-        active:        (r["Active"] || 0).to_i,
-        excludes:      excludes,
-        label:         r["Label"].to_s,
-        source:        source,
-        target:        target,
-        cmd:           r["Cmd"].to_s,
-        sync_file:     r["_note_file"].to_s,
-        source_exists: src_exists,
-        target_exists: tgt_exists,
-        source_mtime:  src_mtime,
-        target_mtime:  tgt_mtime,
-        conflict:      !!conflict,
+        program:          r["Program"].to_s,
+        path:             path,
+        description:      r["Description"].to_s,
+        active:           (r["Active"] || 0).to_i,
+        excludes:         excludes,
+        label:            r["Label"].to_s,
+        source:           source,
+        target:           target,
+        cmd:              r["Cmd"].to_s,
+        delete:           r["Delete"] == true,
+        render:           render,
+        render_outdated:  render_outdated,
+        target_path_field: target_path_field,
+        sync_file:        r["_note_file"].to_s,
+        source_exists:    src_exists,
+        target_exists:    tgt_exists,
+        source_mtime:     src_mtime,
+        target_mtime:     tgt_mtime,
+        conflict:         !!conflict,
       )
     end
 
@@ -139,5 +157,17 @@ module Twin
     rescue Errno::ENOENT, Errno::EACCES
       [false, nil]
     end
+
+    # For a render job: is the target out of date with the rendered template?
+    # nil when source is missing/a directory (status falls through to those).
+    # True when target is absent or content differs, or the template can't be
+    # rendered (unresolved token) — i.e. needs attention.
+    def render_outdated?(src_full, tgt_full, vars, context)
+      return nil unless File.file?(src_full)
+      rendered = Twin::Template.render_file(src_full, vars, context: context)
+      !File.exist?(tgt_full) || File.binread(tgt_full) != rendered
+    rescue
+      true
+    end
   end
 end

data/lib/twin/sync.rb

@@ -4,6 +4,18 @@ module Twin
   module Sync
     module_function
 
+    # A line from `rsync --itemize-changes` describing a real change: an
+    # itemize code whose first column is the update type (< > c h *) and second
+    # the file type (f d L D S), e.g. ">f+++++++++", "cd+++++++++", "*deleting".
+    # No-op runs emit no such line; headers ("sending …", "created directory …")
+    # and the summary don't match. Deterministic — no scraping of prose.
+    ITEMIZE_CHANGE = /\A[<>ch*][fdLDS]/
+
+    # True when rsync reported at least one changed item.
+    def transferred?(output)
+      output.lines.any? { |l| ITEMIZE_CHANGE.match?(l) }
+    end
+
     # True if the path lives on a mounted volume other than the root filesystem.
     # Walks up parents until it finds a mount point (different device than parent)
     # or hits "/" (path is on the root volume, not externally mounted).
@@ -20,16 +32,67 @@ module Twin
       false
     end
 
-    # Sync one Job. Returns [success, combined_output].
+    # Render a template Job: read source, substitute {{vars}}, write if changed.
+    # Returns [success, output, changed].
+    def render_job(cfg, job, dry_run: false)
+      src = job.source_path
+      tgt = job.target_path
+
+      return [false, "source not found: #{src}", false] unless File.exist?(src)
+      return [false, "render: source must be a file, not a directory: #{src}", false] if File.directory?(src)
+
+      begin
+        rendered = Twin::Template.render_file(src, cfg.var_map, context: job.path)
+      rescue => e
+        return [false, e.message, false]
+      end
+
+      if dry_run
+        return [true, "(dry-run) would render #{File.basename(src)} → #{tgt}", false]
+      end
+
+      FileUtils.mkdir_p(File.dirname(tgt))
+
+      current = File.exist?(tgt) ? File.binread(tgt) : nil
+      changed = (current != rendered)
+
+      if changed
+        File.binwrite(tgt, rendered)
+        output = "rendered #{File.basename(src)} → #{tgt}"
+      else
+        output = "#{File.basename(src)}: content unchanged"
+      end
+
+      if !job.cmd.empty?
+        if changed
+          cmd_out, cmd_status = run(["sh", "-c", job.cmd])
+          output += "\ncmd: #{job.cmd}\n#{cmd_out}"
+          unless cmd_status.success?
+            output += "cmd failed (exit #{cmd_status.exitstatus})"
+            return [false, output, changed]
+          end
+        else
+          output += "\ncmd skipped (content unchanged)"
+        end
+      end
+
+      [true, output, changed]
+    end
+
+    # Sync one Job. Returns [success, combined_output, transferred].
+    # transferred is true when rsync actually moved bytes (false on no-op or dry_run).
     def run_job(cfg, job, dry_run: false)
+      return render_job(cfg, job, dry_run: dry_run) if job.render
+
       src = job.source_path
       tgt = job.target_path
 
-      return [false, "source not found: #{src}"] unless File.exist?(src)
+      return [false, "source not found: #{src}", false] unless File.exist?(src)
 
       FileUtils.mkdir_p(File.dirname(tgt))
 
-      args = ["rsync", "-av", "--update"]
+      args = ["rsync", "-av", "--itemize-changes", "--update"]
+      args << "--delete" if job.delete
       args << "--dry-run" if dry_run
       cfg.global_excludes.each { |ex| args << "--exclude=#{ex}" }
       job.excludes.each       { |ex| args << "--exclude=#{ex}" }
@@ -41,15 +104,28 @@ module Twin
       end
 
       output, status = run(args)
-      return [false, output] unless status.success?
+      return [false, output, false] unless status.success?
+
+      xfr = !dry_run && transferred?(output)
+
+      if job.conflict && !xfr && !dry_run
+        output += "\nskipped: target is newer, source not synced"
+      end
 
       if !job.cmd.empty? && !dry_run
-        cmd_out, cmd_status = run(["sh", "-c", job.cmd])
-        output += "\ncmd: #{job.cmd}\n#{cmd_out}"
-        return [false, output] unless cmd_status.success?
+        if xfr
+          cmd_out, cmd_status = run(["sh", "-c", job.cmd])
+          output += "\ncmd: #{job.cmd}\n#{cmd_out}"
+          unless cmd_status.success?
+            output += "cmd failed (exit #{cmd_status.exitstatus})"
+            return [false, output, xfr]
+          end
+        else
+          output += "\ncmd skipped (nothing transferred)"
+        end
       end
 
-      [true, output]
+      [true, output, xfr]
     end
 
     # Sync all jobs in a Program. Returns array of [job, success, output].

data/lib/twin/template.rb

@@ -0,0 +1,36 @@
+module Twin
+  module Template
+    PATTERN = /\{\{([^}]+)\}\}/
+
+    # Fields in a grubber record that may contain {{tokens}}.
+    FIELDS = %w[Source Target Path Target-Path Exclude Cmd].freeze
+
+    module_function
+
+    # Replace {{token}} in value using vars. Raises on unknown token.
+    def substitute(value, vars, context:)
+      return value unless value.is_a?(String)
+      value.gsub(PATTERN) do
+        token = $1
+        vars.fetch(token) { raise "unknown template token {{#{token}}} in #{context}" }
+      end
+    end
+
+    # Read a template file and substitute {{tokens}} in its content.
+    # Binary read preserves bytes exactly; raises on unknown token.
+    def render_file(path, vars, context:)
+      substitute(File.binread(path), vars, context: context)
+    end
+
+    # Return a copy of grubber record r with FIELDS substituted.
+    def substitute_record(r, vars, context:)
+      return r if vars.empty?
+      result = r.dup
+      FIELDS.each do |field|
+        next unless result.key?(field) && result[field].is_a?(String)
+        result[field] = substitute(result[field], vars, context: context)
+      end
+      result
+    end
+  end
+end

data/lib/twin/version.rb

@@ -1,3 +1,3 @@
 module Twin
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/twin.rb

@@ -1,4 +1,5 @@
 require_relative "twin/version"
+require_relative "twin/template"
 require_relative "twin/config"
 require_relative "twin/scanner"
 require_relative "twin/sync"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mark-twin
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Ralf Hülsmann
@@ -43,6 +43,7 @@ files:
 - lib/twin/preview.rb
 - lib/twin/scanner.rb
 - lib/twin/sync.rb
+- lib/twin/template.rb
 - lib/twin/version.rb
 homepage: https://github.com/rhsev/mark-twin
 licenses: