mark-twin 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70005ba12f4a11cde04a57fd68615d3478d2ca974f2aaa6eb49d650c2201a9ac
+  data.tar.gz: c0e5e45e52cdb20c5758ce11c0b81fdc20b309a1cc9c637a146833b001424e05
+SHA512:
+  metadata.gz: 05ae1ff58350d3fcde9d3ac959859f474c585d1e9a11ce5141a36093aa77d597362529c33bc17b4774b7eb7aecf1330c70baf84392a6de081b2fab3ee7c918cc
+  data.tar.gz: 7a730c9622eaaf684b5f4805fb93a19d84a53344b415eec873ab14701ae3a6b77515a2806437e333b408db4a742397390b1f02bc7c4ad6791585ac480e27e1b7

data/ARCHITECTURE.md

@@ -0,0 +1,138 @@
+# Architecture
+
+## Overview
+
+```
+sync-files (.md)
+      │
+      ▼
+   grubber          parse Markdown, extract YAML blocks, merge frontmatter
+      │
+      ▼
+   Scanner          load_jobs → list[Job] → group(jobs) → list[Program]
+      │
+      ├──▶  CLI       list / status / sync
+      │
+      └──▶  Picker    fzf + apex preview, returns selected Program
+                          │
+                          ▼
+                       Sync   rsync per Job, mount check, Cmd hook
+```
+
+## Package layout
+
+```
+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
+  picker.rb     fzf wrapper with apex preview
+  cli.rb        subcommand dispatcher
+
+bin/twin        entrypoint
+test/test_pure.rb
+```
+
+## Data model
+
+**Job** — one YAML block:
+
+```
+program, path, description, active, excludes, label, source, target, cmd, 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`.
+
+**Program** — group of Jobs sharing a `program` name:
+
+```
+name, jobs
+```
+
+`Program#status` aggregates jobs (worst state wins). Selection in the picker
+operates on Programs, not individual Jobs.
+
+## Configuration
+
+`~/.config/twin/config.yaml`:
+
+```yaml
+sync_dir: /path/to/sync-files
+global_excludes: [".DS_Store", ".git/"]
+apex_theme: ralf
+apex_width: 80
+```
+
+Environment overrides: `TWIN_SYNC_DIR` (sync_dir), `TWIN_CONFIG` (config path).
+
+## Sync-files
+
+Markdown files. Frontmatter is the sync-relationship (source/target). YAML
+blocks define paths. grubber merges frontmatter into each block so every
+record is self-contained.
+
+Multiple blocks may share the same `Program` value — these are treated as
+one logical unit by twin.
+
+## Picker
+
+Two stages:
+
+1. **Stage 1 — program picker.** Multi-line NUL-separated entries (`--read0`).
+   Each entry has a header (icon, program name, job count, sync-file) and
+   indented body lines (one per job). No preview. Single-select. ESC exits.
+2. **Stage 2 — path multi-picker.** Tab-delimited rows (`id\tdisplay`),
+   `--with-nth=2` hides the `id`. Multi-select via Tab. Preview pane shows
+   the *compact* view (frontmatter + intro + the heading section containing
+   the YAML block for the highlighted path), rendered via
+   `apex --plugins -t terminal256`. ESC returns to Stage 1.
+
+Compact previews are pre-rendered to per-job tempfiles before fzf launches.
+An `awk` lookup maps `{1}` (the id) → tempfile path.
+
+## CLI
+
+File argument resolution (`twin <arg>` and `--file=<arg>`):
+
+- empty / missing       → scan `sync_dir`, no filter
+- bare name (no `/`)    → scan `sync_dir`, filter by substring match
+- path containing `/`   → expand, then:
+  - directory           → scan that directory, no filter
+  - file                → scan parent directory, filter by basename
+  - neither             → raise "not found: …"
+
+Unknown options (anything starting with `-` that isn't `--help`) print an
+error pointing at `twin --help` and exit 1.
+
+## Sync
+
+Before syncing:
+
+1. **Mount check** — every unique target root must be a mount point
+   (`File.stat.dev != parent.dev`). Aborts if unmounted.
+2. **Conflict warning** — emits stderr listing jobs where the target is
+   newer than the source. Continues anyway (`rsync --update` skips them).
+
+Then per Job:
+
+```
+rsync -av --update [--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.
+
+## External dependencies
+
+| Tool      | Purpose                                    |
+|-----------|--------------------------------------------|
+| `grubber` | Markdown + YAML block extraction           |
+| `rsync`   | File transfer                              |
+| `fzf`     | Interactive selection                      |
+| `apex`    | Markdown preview rendering in the terminal |
+
+twin has no runtime gem dependencies — only stdlib (`yaml`, `json`,
+`optparse`, `open3`, `fileutils`).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ralf Hülsmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# twin
+
+[![Gem Version](https://img.shields.io/gem/v/mark-twin.svg)](https://rubygems.org/gems/mark-twin)
+[![Tests](https://github.com/rhsev/mark-twin/actions/workflows/test.yml/badge.svg)](https://github.com/rhsev/mark-twin/actions/workflows/test.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Sync configuration folders between two Macs from self-documenting Markdown files.
+
+Sync entries are defined in Markdown files with YAML blocks — human-readable,
+self-documenting, and queryable via [grubber](https://github.com/rhsev/grubber).
+Selection is interactive via [fzf](https://github.com/junegunn/fzf), with a
+Markdown preview rendered by [apex](https://github.com/ttscoff/apex) and
+optional post-sync actions on the target via [mi.lan](https://github.com/rhsev/mi.lan).
+
+## Why?
+
+Sync-definitions in Markdown + YAML are three things at once:
+
+- **Human-readable.** Plain Markdown, no twin-specific syntax to learn. The
+  Markdown frame documents *why* a path is synced, not just what, so you can
+  read your own sync-files in a year and still understand them.
+- **Machine-readable.** The YAML blocks are queryable via grubber, so any tool
+  (twin, but also future ones) can act on the same source of truth.
+- **AI-writable.** LLMs handle Markdown + YAML well. You can ask an assistant to
+  add new entries or refactor existing ones, and the result stays valid for both
+  humans and grubber.
+
+## Screenshots
+
+Stage 1 — program picker. One row per program, color-coded status, indented
+paths underneath:
+
+![Stage 1 — program picker](https://raw.githubusercontent.com/rhsev/mark-twin/main/docs/stage_1.png)
+
+Stage 2 — multi-select over the paths of one program. The right pane shows a
+compact preview of the relevant sync-file section, rendered by apex:
+
+![Stage 2 — Fish Shell paths with apex preview](https://raw.githubusercontent.com/rhsev/mark-twin/main/docs/stage_2_fish.png)
+
+## Installation
+
+### 1. Install grubber
+
+twin parses sync-files via [grubber](https://github.com/rhsev/grubber), a
+small Go binary. Download the latest release for your platform from
+[github.com/rhsev/grubber/releases](https://github.com/rhsev/grubber/releases)
+and put it somewhere in your `PATH` (e.g. `/usr/local/bin/grubber`).
+
+### 2. Install twin
+
+```bash
+gem install mark-twin
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/rhsev/mark-twin.git
+cd mark-twin
+gem build mark-twin.gemspec
+gem install ./mark-twin-*.gem
+```
+
+### 3. Other tools
+
+Also required in `PATH`: `rsync` (preinstalled on macOS), `fzf`
+(`brew install fzf`). For the stage-2 preview, one of `apex`, `glow`,
+or `bat` is recommended (falls back in that order; `cat` if none are
+present).
+
+## Quickstart
+
+Twin assumes the target machine is reachable as a mounted volume (typically
+via SMB or NFS). The mount check is enforced before any sync.
+
+1. **Pick a directory for sync-files** (anywhere; this example uses `~/Sync`):
+
+   ```bash
+   mkdir -p ~/Sync
+   ```
+
+2. **Create the config** at `~/.config/twin/config.yaml`:
+
+   ```yaml
+   sync_dir: ~/Sync
+   global_excludes:
+     - .DS_Store
+     - .git/
+   ```
+
+3. **Drop a sync-file** into `~/Sync`. The simplest starting point is to copy
+   one of the [examples](examples/) and adapt the frontmatter:
+
+   ```bash
+   cp examples/home.md ~/Sync/
+   $EDITOR ~/Sync/home.md   # edit Source: and Target:
+   ```
+
+4. **Run twin**:
+
+   ```bash
+   twin
+   ```
+
+   Pick a program, then the paths to sync, hit Enter.
+
+## Usage
+
+Twin has two modes: an **interactive interface** (default — see screenshots
+above) and **CLI commands** for status checks and batch sync.
+
+```bash
+twin                         # TUI — all programs across all sync-files
+twin home.md                 # TUI — one sync-file in sync_dir (by name)
+twin /abs/path/to/file.md    # TUI — any sync-file by absolute path
+twin ./relative/dir/         # TUI — all sync-files in a directory
+twin list                    # plain listing
+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 --help                  # show usage
+```
+
+File argument resolution:
+
+- bare name (no `/`)  → looked up by substring in `sync_dir`
+- contains `/`        → resolved as path (absolute or relative); file or directory both work
+
+## Configuration
+
+`~/.config/twin/config.yaml`:
+
+```yaml
+sync_dir: /path/to/sync-files
+
+global_excludes:
+  - .DS_Store
+  - .git/
+
+# Optional preview rendering (apex):
+# apex_theme: default
+# apex_width: 80
+# apex_code_highlight: monokai
+# apex_code_highlight_theme: dark
+```
+
+Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`.
+
+## Sync-files
+
+Each Markdown file represents one sync relationship. Frontmatter defines the
+relationship (Source/Target); YAML blocks define individual paths.
+
+See [examples/home.md](examples/home.md) and [examples/repos.md](examples/repos.md)
+for ready-to-adapt templates.
+
+Minimal example:
+
+````markdown
+---
+Active: 1
+Label: mac-mini → macbook
+Source: /Users/admin
+Target: /Volumes/macbook/Users/admin
+---
+
+## Fish Shell
+
+Configuration for the fish shell, including completions and abbreviations.
+
+```yaml
+Program: Fish Shell
+Path: .config/fish
+Description: Fish Shell configuration
+Exclude: conf.d/local.fish
+```
+````
+
+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).
+
+## Design
+
+Sync instructions and context in one place — the same Markdown file holds
+both the `Path:` directives and the prose explaining them. No TUI framework:
+`fzf` does the interactive part, `apex` the rendering.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the data model and internals.
+
+## Tests
+
+```bash
+rake test
+```

data/bin/twin

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "twin"
+
+Twin::CLI.run(ARGV)

data/lib/twin/cli.rb

@@ -0,0 +1,242 @@
+require "optparse"
+require "json"
+require "set"
+
+require_relative "config"
+require_relative "scanner"
+require_relative "sync"
+require_relative "picker"
+
+module Twin
+  module CLI
+    module_function
+
+    USAGE = <<~TXT
+      twin — sync configuration files between machines
+
+      USAGE:
+        twin                       interactive picker (all sync-files)
+        twin <name>                picker — sync-file by name in sync_dir
+        twin <path>                picker — file or directory (absolute or relative)
+        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 --help                show this message
+
+      FILE ARGUMENT:
+        bare name (no /)  → matched by substring against sync-file names
+        contains /        → resolved as path; file or directory both work
+
+      CONFIG:
+        ~/.config/twin/config.yaml
+        TWIN_SYNC_DIR  overrides sync_dir
+        TWIN_CONFIG    overrides config path
+    TXT
+
+    def run(argv)
+      cfg = Twin::Config.load
+      cfg.validate!
+
+      first = argv.first
+      case first
+      when nil
+        pick_and_sync(cfg, file: nil)
+      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 "-h", "--help", "help"
+        puts USAGE
+      when /\A-/
+        warn "unknown option: #{first}"
+        warn "Run 'twin --help' for usage."
+        exit 1
+      else
+        # Treat as file.md or directory path
+        pick_and_sync(cfg, file: first)
+      end
+    rescue => e
+      warn "error: #{e.message}"
+      exit 1
+    end
+
+    # ── picker → sync ──────────────────────────────────────────────────────────
+
+    def pick_and_sync(cfg, file:)
+      programs = Scanner.load_programs(cfg, file: file, show_all: false)
+      if programs.empty?
+        warn "no active programs found#{" in #{file}" if file}"
+        return
+      end
+
+      selected_key = nil  # [name, sync_file] of last program — used to re-enter
+      loop do
+        program =
+          if selected_key
+            programs.find { |p| [p.name, p.sync_file] == selected_key }
+          else
+            Picker.pick_program(programs)
+          end
+        return unless program
+
+        jobs = Picker.pick_paths(program, cfg)
+        if jobs == :back               # ESC in stage 2 → back to stage 1
+          selected_key = nil
+          next
+        end
+        if jobs.empty?                 # Enter without selection → exit
+          return
+        end
+
+        sync_jobs(cfg, program, jobs)
+
+        print "\npress Enter to continue, q to quit "
+        $stdout.flush
+        break if $stdin.gets&.strip == "q"
+
+        # reload so status reflects what was just synced, stay on this program
+        programs     = Scanner.load_programs(cfg, file: file, show_all: false)
+        selected_key = [program.name, program.sync_file]
+      end
+    end
+
+    # ── list / status ──────────────────────────────────────────────────────────
+
+    def cmd_list(cfg, args)
+      opts = parse_filter_opts(args)
+      programs = Scanner.load_programs(cfg, **opts.slice(:file, :label, :show_all))
+
+      if opts[:json]
+        puts JSON.pretty_generate(programs.map { |p| program_to_hash(p) })
+        return
+      end
+
+      programs.each do |p|
+        mark = p.status == :disabled ? "–" : "✓"
+        puts "#{mark}  #{p.name}  — #{p.description}"
+      end
+    end
+
+    def cmd_status(cfg, args)
+      opts = parse_filter_opts(args)
+      programs = Scanner.load_programs(cfg, **opts.slice(:file, :label, :show_all))
+
+      if opts[:json]
+        puts JSON.pretty_generate(programs.map { |p| program_to_hash(p) })
+        return
+      end
+
+      tty = $stdout.tty?
+      programs.each do |p|
+        icon = Picker::STATUS_ICONS[p.status] || "?"
+        icon = Picker.colorize(p.status, icon) if tty
+        name = tty ? Picker.bold(p.name) : p.name
+        puts "#{icon}  #{name}"
+        p.jobs.each do |j|
+          src = j.source_exists ? j.source_mtime.strftime("%Y-%m-%d %H:%M:%S") : "(not found)"
+          tgt = j.target_exists ? j.target_mtime.strftime("%Y-%m-%d %H:%M:%S") : "(not found)"
+          conflict = j.conflict ? (tty ? "  #{Picker.colorize(:target_newer, "!")}" : "  !") : ""
+          puts "    #{j.path}#{conflict}"
+          puts "      src #{src}"
+          puts "      dst #{tgt}"
+        end
+      end
+    end
+
+    # ── sync ───────────────────────────────────────────────────────────────────
+
+    def cmd_sync(cfg, args)
+      opts = parse_sync_opts(args)
+      programs = Scanner.load_programs(cfg, **opts.slice(:file, :label, :show_all))
+
+      if opts[:pattern]
+        programs = programs.select { |p| p.name.downcase.include?(opts[:pattern].downcase) }
+      end
+
+      if programs.empty?
+        puts "no matching programs"
+        return
+      end
+
+      programs.each { |p| sync_program(cfg, p, dry_run: opts[:dry_run]) }
+    end
+
+    def sync_program(cfg, program, dry_run: false)
+      sync_jobs(cfg, program, program.active_jobs, dry_run: dry_run)
+    end
+
+    def sync_jobs(cfg, program, jobs, dry_run: false)
+      jobs = jobs.select { |j| j.active == 1 }
+      return if jobs.empty?
+
+      # one mount check per unique target root
+      checked = Set.new
+      jobs.each do |j|
+        next if checked.include?(j.target)
+        unless Twin::Sync.mounted?(j.target)
+          warn "abort: #{j.target} is not a mounted volume"
+          exit 1
+        end
+        checked << j.target
+      end
+
+      conflicts = jobs.select(&:conflict)
+      unless conflicts.empty?
+        warn "warning: target is newer than source:"
+        conflicts.each { |j| warn "  ! #{j.path}" }
+        warn "continuing sync (--update skips newer files on target)."
+      end
+
+      puts "→ #{program.name}"
+      jobs.each do |job|
+        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
+
+    # ── option parsing ─────────────────────────────────────────────────────────
+
+    def parse_filter_opts(args)
+      opts = { show_all: false, label: nil, file: nil, json: false }
+      OptionParser.new do |o|
+        o.on("--all")          { opts[:show_all] = true }
+        o.on("--label=L")      { |v| opts[:label] = v }
+        o.on("--file=F")       { |v| opts[:file] = v }
+        o.on("--json")         { opts[:json] = true }
+      end.parse!(args)
+      opts
+    end
+
+    def parse_sync_opts(args)
+      opts = { show_all: false, label: nil, file: nil, pattern: nil, dry_run: false }
+      OptionParser.new do |o|
+        o.on("--all")          { opts[:show_all] = true }
+        o.on("--label=L")      { |v| opts[:label] = v }
+        o.on("--file=F")       { |v| opts[:file] = v }
+        o.on("-p", "--pattern=P") { |v| opts[:pattern] = v }
+        o.on("--dry-run")      { opts[:dry_run] = true }
+      end.parse!(args)
+      opts
+    end
+
+    def program_to_hash(p)
+      {
+        name:        p.name,
+        status:      p.status,
+        sync_file:   p.sync_file,
+        label:       p.label,
+        description: p.description,
+        jobs:        p.jobs.map { |j| job_to_hash(j) },
+      }
+    end
+
+    def job_to_hash(j)
+      h = j.to_h
+      h[:status]       = j.status
+      h[:source_mtime] = j.source_mtime&.iso8601
+      h[:target_mtime] = j.target_mtime&.iso8601
+      h
+    end
+  end
+end

data/lib/twin/config.rb

@@ -0,0 +1,46 @@
+require "yaml"
+require "pathname"
+
+module Twin
+  class Config
+    attr_accessor :sync_dir, :global_excludes,
+                  :apex_theme, :apex_width,
+                  :apex_code_highlight, :apex_code_highlight_theme
+
+    DEFAULTS = {
+      "global_excludes"           => [".DS_Store"],
+      "apex_theme"                => nil,
+      "apex_width"                => nil,
+      "apex_code_highlight"       => nil,
+      "apex_code_highlight_theme" => nil,
+    }.freeze
+
+    def initialize(data = {})
+      merged = DEFAULTS.merge(data || {})
+      @sync_dir                  = ENV["TWIN_SYNC_DIR"] || merged["sync_dir"].to_s
+      @global_excludes           = merged["global_excludes"] || []
+      @apex_theme                = merged["apex_theme"]
+      @apex_width                = merged["apex_width"]
+      @apex_code_highlight       = merged["apex_code_highlight"]
+      @apex_code_highlight_theme = merged["apex_code_highlight_theme"]
+    end
+
+    def self.load
+      path = ENV["TWIN_CONFIG"] || File.join(Dir.home, ".config", "twin", "config.yaml")
+      data = {}
+      if File.exist?(path)
+        begin
+          data = YAML.safe_load_file(path) || {}
+        rescue Psych::SyntaxError => e
+          raise "config syntax error in #{path}: #{e.message}"
+        end
+      end
+      new(data)
+    end
+
+    def validate!
+      raise "sync_dir not set (add to ~/.config/twin/config.yaml or set TWIN_SYNC_DIR)" if sync_dir.empty?
+      raise "sync_dir not found: #{sync_dir}" unless Dir.exist?(sync_dir)
+    end
+  end
+end

data/lib/twin/picker.rb

@@ -0,0 +1,213 @@
+require "open3"
+require "tempfile"
+
+require_relative "preview"
+
+module Twin
+  # Two-step fzf picker:
+  #   pick_program → tabular multi-line list, no preview
+  #   pick_paths   → multi-select within one program, glow renders the sync-file
+  module Picker
+    module_function
+
+    STATUS_ICONS = {
+      source_newer:   "→",
+      target_newer:   "←",
+      in_sync:        "✓",
+      missing_target: "!",
+      missing_source: "!",
+      both_missing:   "✗",
+      disabled:       "·",
+    }.freeze
+
+    STATUS_COLORS = {
+      source_newer:   "\e[33m",   # yellow
+      target_newer:   "\e[36m",   # cyan
+      in_sync:        "\e[32m",   # green
+      missing_target: "\e[31m",   # red
+      missing_source: "\e[31m",   # red
+      both_missing:   "\e[31m",   # red
+      disabled:       "\e[2m",    # dim
+    }.freeze
+
+    BOLD  = "\e[1m"
+    DIM   = "\e[2m"
+    RESET = "\e[0m"
+
+    SH_ENV = { "SHELL" => "/bin/sh" }.freeze
+
+    def colorize(status, text) = "#{STATUS_COLORS[status] || ''}#{text}#{RESET}"
+    def dim(text)              = "#{DIM}#{text}#{RESET}"
+    def bold(text)             = "#{BOLD}#{text}#{RESET}"
+
+    # ── Stufe 1: program picker ───────────────────────────────────────────────
+
+    # Multi-line entries (NUL-separated). Header line per program, indented
+    # body lines per job. Returns the selected Program or nil.
+    def pick_program(programs)
+      raise "fzf not found in PATH" unless which("fzf")
+      return nil if programs.empty?
+
+      name_width = programs.map { |p| p.name.length }.max
+      path_width = programs.flat_map { |p| p.jobs.map { |j| j.path.length } }.max
+
+      entries = programs.each_with_index.map do |p, i|
+        "#{i}\t#{render_program_entry(p, name_width, path_width)}"
+      end
+      input = entries.join("\0")
+
+      fzf = [
+        "fzf",
+        "--read0", "--ansi", "--no-multi",
+        "--delimiter=\t", "--with-nth=2..",
+        "--prompt=program> ",
+        "--height=100%", "--reverse",
+        "--no-sort",
+        "--color=bg+:-1,hl+:reverse",
+      ]
+
+      output, status = Open3.capture2(SH_ENV, *fzf, stdin_data: input)
+      return nil unless status.success?
+      return nil if output.strip.empty?
+
+      idx = output.split("\t", 2).first
+      programs[idx.to_i] if idx&.match?(/\A\d+\z/)
+    end
+
+    # ── Stufe 2: path multi-picker ────────────────────────────────────────────
+
+    # Multi-select over the jobs of one program. Right pane shows the
+    # apex-rendered compact view (frontmatter + intro + selected block).
+    # Returns array of selected Jobs, :back on ESC, [] on empty confirm.
+    def pick_paths(program, cfg)
+      jobs = program.jobs
+      return [] if jobs.empty?
+
+      path_width = jobs.map { |j| j.path.length }.max
+      tempfiles  = write_compact_previews(program, jobs)
+      preview_cmd, mapfile = build_apex_preview_cmd(tempfiles, cfg)
+
+      rows = jobs.each_with_index.map do |j, i|
+        icon  = STATUS_ICONS[j.status] || "?"
+        delta = format_delta(j.source_mtime, j.target_mtime)
+        line  = "#{icon}  #{j.path.ljust(path_width)}  #{delta}"
+        "#{i}\t#{colorize(j.status, line)}"
+      end
+
+      fzf = [
+        "fzf",
+        "--multi", "--ansi",
+        "--delimiter=\t", "--with-nth=2",
+        "--prompt=#{program.name} > ",
+        "--header=#{program.name} — Tab toggles, Enter confirms",
+        "--preview=#{preview_cmd}",
+        "--preview-window=right:60%:wrap",
+        "--height=100%", "--reverse",
+        "--bind=ctrl-a:select-all",
+        "--color=bg+:-1,hl+:reverse",
+      ]
+
+      output, status = Open3.capture2(SH_ENV, *fzf, stdin_data: rows.join("\n"))
+      return :back if status.exitstatus == 130   # ESC / Ctrl-C
+      return [] unless status.success?
+      return [] if output.strip.empty?
+
+      output.lines.filter_map do |line|
+        idx = line.split("\t", 2).first&.to_i
+        jobs[idx] if idx
+      end
+    ensure
+      tempfiles&.each_value { |path| File.unlink(path) rescue nil }
+      File.unlink(mapfile) rescue nil if mapfile
+    end
+
+    # Write per-job compact-preview markdown to tempfiles. Returns {idx => path}.
+    def write_compact_previews(program, jobs)
+      result = {}
+      jobs.each_with_index do |job, i|
+        compact = Preview.extract_compact(program.sync_file, job.path)
+        f = Tempfile.new(["twin-#{i}-", ".md"])
+        f.write(compact)
+        f.close
+        result[i] = f.path
+      end
+      result
+    end
+
+    # Returns [preview_cmd, mapfile_path]; the caller unlinks the mapfile.
+    def build_apex_preview_cmd(tempfiles, cfg)
+      # Map idx → file via a small TSV, awk picks the right one for {1}.
+      mapfile = Tempfile.new(["twin-map-", ".tsv"])
+      tempfiles.each { |i, path| mapfile.puts("#{i}\t#{path}") }
+      mapfile.close
+
+      render_cmd = pick_renderer(cfg)
+
+      cmd = %(F=$(awk -v id={1} -F'\\t' '$1==id {print $2}' #{mapfile.path}); ) +
+            %([ -n "$F" ] && #{render_cmd})
+      [cmd, mapfile.path]
+    end
+
+    # Pick the first available markdown renderer.
+    def pick_renderer(cfg)
+      if which("apex")
+        args = ["--plugins", "-t", "terminal256"]
+        args += ["--theme", shellesc(cfg.apex_theme)]                         if cfg.apex_theme
+        args += ["--width", shellesc(cfg.apex_width)]                         if cfg.apex_width
+        args += ["--code-highlight", shellesc(cfg.apex_code_highlight)]       if cfg.apex_code_highlight
+        args += ["--code-highlight-theme", shellesc(cfg.apex_code_highlight_theme)] if cfg.apex_code_highlight_theme
+        (["apex", '"$F"'] + args).join(" ") + " 2>/dev/null"
+      elsif which("glow")
+        %(glow -s dark "$F" 2>/dev/null)
+      elsif which("bat")
+        %(bat --color=always --language=markdown --style=plain "$F" 2>/dev/null)
+      else
+        %(cat "$F")
+      end
+    end
+
+    def which(cmd)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+        File.executable?(File.join(dir, cmd))
+      end
+    end
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def render_program_entry(program, name_width, path_width)
+      icon      = colorize(program.status, STATUS_ICONS[program.status] || "?")
+      sync_file = File.basename(program.sync_file.to_s)
+      count     = program.active_jobs.size
+      total     = program.jobs.size
+      header    = "#{icon}  #{bold(program.name.ljust(name_width))}    " \
+                  "#{dim("(#{count}/#{total})")}    #{dim("[#{sync_file}]")}"
+
+      body = program.jobs.map do |j|
+        icon  = STATUS_ICONS[j.status] || "?"
+        delta = format_delta(j.source_mtime, j.target_mtime)
+        line  = "    #{icon}  #{j.path.ljust(path_width)}  #{delta}"
+        colorize(j.status, line)
+      end
+
+      ([header] + body).join("\n")
+    end
+
+    def format_delta(sm, tm)
+      return "" if sm.nil? || tm.nil?
+      seconds = (sm - tm).to_i
+      return "in sync" if seconds.abs < 60
+      label = seconds > 0 ? "src" : "tgt"
+      abs = seconds.abs
+      unit =
+        if abs >= 86400 then "#{abs / 86400}d"
+        elsif abs >= 3600 then "#{abs / 3600}h"
+        else "#{abs / 60}m"
+        end
+      "#{label} +#{unit}"
+    end
+
+    def shellesc(s)
+      "'" + s.to_s.gsub("'", %q['\\''])  + "'"
+    end
+  end
+end

data/lib/twin/preview.rb

@@ -0,0 +1,92 @@
+module Twin
+  # Compact markdown preview for a single sync block: frontmatter +
+  # intro (text before the first heading) + the heading section that
+  # contains the YAML block for *target_path*.
+  module Preview
+    module_function
+
+    YAML_FENCE = /\A```ya?ml\s*\z/.freeze
+    FENCE_END  = /\A```\s*\z/.freeze
+    HEADING    = /\A(\#{1,6})\s/.freeze
+    H2_PLUS    = /\A\#{2,6}\s/.freeze
+    PATH_KEY   = /\APath:\s*['"]?([^'"]+?)['"]?\s*\z/.freeze
+
+    def extract_compact(file_path, target_path)
+      content = File.read(file_path, encoding: "UTF-8")
+
+      frontmatter, body = split_frontmatter(content)
+      lines = body.lines.map(&:chomp)
+
+      intro     = extract_intro(lines)
+      section   = extract_section_for(lines, target_path)
+
+      [frontmatter, intro, section].reject(&:empty?).join("\n\n") + "\n"
+    rescue Errno::ENOENT
+      ""
+    end
+
+    def split_frontmatter(content)
+      return ["", content] unless content.start_with?("---\n") || content.start_with?("---\r\n")
+      parts = content.split(/^---\s*$\n/, 3)
+      return ["", content] if parts.size < 3
+      ["---\n#{parts[1]}---", parts[2]]
+    end
+
+    # Intro = everything up to the first H2 (H1 + body counts as document title).
+    def extract_intro(lines)
+      idx = lines.index { |l| l =~ H2_PLUS }
+      idx = lines.size unless idx
+      lines[0...idx].join("\n").strip
+    end
+
+    # Locate the YAML block whose Path: matches *target*, then return the
+    # surrounding heading section (nearest preceding heading until the next
+    # heading of equal-or-higher level).
+    def extract_section_for(lines, target)
+      block_start, block_end = find_block(lines, target)
+      return "" unless block_start
+
+      section_start = block_start
+      (block_start - 1).downto(0) do |i|
+        if lines[i] =~ HEADING
+          section_start = i
+          break
+        end
+      end
+
+      section_end = lines.size - 1
+      if (m = lines[section_start]&.match(HEADING))
+        level = m[1].length
+        ((block_end + 1)...lines.size).each do |i|
+          if (m2 = lines[i].match(HEADING)) && m2[1].length <= level
+            section_end = i - 1
+            break
+          end
+        end
+      end
+
+      lines[section_start..section_end].join("\n").strip
+    end
+
+    def find_block(lines, target)
+      i = 0
+      while i < lines.size
+        if lines[i] =~ YAML_FENCE
+          k = i + 1
+          matched = false
+          while k < lines.size && lines[k] !~ FENCE_END
+            if (m = lines[k].match(PATH_KEY)) && m[1] == target
+              matched = true
+            end
+            k += 1
+          end
+          return [i, k] if matched
+          i = k + 1
+        else
+          i += 1
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/twin/scanner.rb

@@ -0,0 +1,143 @@
+require "json"
+require "open3"
+
+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_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 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
+      return :target_newer if conflict
+      return :in_sync if source_mtime.nil? || target_mtime.nil?
+      delta = source_mtime - target_mtime
+      return :in_sync if delta.abs < 60
+      delta > 0 ? :source_newer : :target_newer
+    end
+  end
+
+  # A logical group of Jobs sharing a Program name (e.g. "Matterbase" can have
+  # multiple paths). Selection unit in the picker.
+  Program = Struct.new(:name, :jobs, keyword_init: true) do
+    def sync_file = jobs.first&.sync_file
+    def label     = jobs.first&.label
+
+    def description
+      jobs.map(&:description).reject(&:empty?).uniq.join(" / ")
+    end
+
+    # Aggregate status across jobs — worst first.
+    def status
+      states = jobs.map(&:status)
+      %i[both_missing missing_source missing_target target_newer source_newer disabled in_sync]
+        .find { |s| states.include?(s) } || :in_sync
+    end
+
+    def active_jobs = jobs.select { |j| j.active == 1 }
+
+    def newest_source_mtime = jobs.map(&:source_mtime).compact.max
+    def newest_target_mtime = jobs.map(&:target_mtime).compact.max
+  end
+
+  module Scanner
+    module_function
+
+    def load_jobs(cfg, scan_path: nil)
+      raise "grubber not found in PATH" unless system("command -v grubber > /dev/null 2>&1")
+
+      dir = scan_path || cfg.sync_dir
+      stdout, stderr, status = Open3.capture3(
+        "grubber", "extract", dir, "-b", "--format", "json"
+      )
+      raise "grubber: #{stderr.force_encoding('UTF-8').strip}" unless status.success?
+
+      begin
+        records = JSON.parse(stdout.force_encoding("UTF-8"))
+      rescue JSON::ParserError => e
+        raise "grubber returned invalid JSON: #{e.message}"
+      end
+      records.filter_map { |r| build_job(r) }
+    end
+
+    def load_programs(cfg, file: nil, label: nil, show_all: false)
+      scan_path, name_filter = resolve_file_arg(cfg, file)
+      jobs = load_jobs(cfg, scan_path: scan_path)
+      jobs = jobs.select { |j| j.sync_file.include?(name_filter) } if name_filter
+      jobs = jobs.select { |j| j.label == label }                   if label && !label.empty?
+      jobs = jobs.select { |j| j.active == 1 }                     unless show_all
+      group(jobs)
+    end
+
+    # Returns [scan_path, name_filter] for a given file argument.
+    # - nil / empty        → [nil, nil]           scan sync_dir, no filter
+    # - path to a dir      → [dir, nil]            scan that dir, no filter
+    # - path to a file     → [dirname, basename]   scan parent dir, filter by filename
+    # - bare name (no /)   → [nil, name]           scan sync_dir, filter by name
+    def resolve_file_arg(cfg, file)
+      return [nil, nil] if file.nil? || file.empty?
+      if file.include?("/") || file == "." || file == ".."
+        expanded = File.expand_path(file)
+        return [expanded, nil]                             if File.directory?(expanded)
+        return [File.dirname(expanded), File.basename(expanded)] if File.file?(expanded)
+        raise "not found: #{file}"
+      end
+      [nil, file]
+    end
+
+    def group(jobs)
+      jobs.group_by { |j| [j.program, j.sync_file] }
+          .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
+      return nil if path.empty? || source.empty? || target.empty?
+
+      excludes = (r["Exclude"] || "").split(",").map(&:strip).reject(&:empty?)
+
+      src_full = File.join(source, path)
+      tgt_full = File.join(target, path)
+      src_exists, src_mtime = stat(src_full)
+      tgt_exists, tgt_mtime = stat(tgt_full)
+      # Same 60s tolerance as Job#status, so mtime jitter never flags a conflict.
+      conflict = 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,
+      )
+    end
+
+    def stat(path)
+      st = File.stat(path)
+      [true, st.mtime]
+    rescue Errno::ENOENT, Errno::EACCES
+      [false, nil]
+    end
+  end
+end

data/lib/twin/sync.rb

@@ -0,0 +1,68 @@
+require "fileutils"
+
+module Twin
+  module Sync
+    module_function
+
+    # 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).
+    def mounted?(path)
+      return false unless File.exist?(path)
+      current = File.expand_path(path)
+      until current == "/"
+        parent = File.expand_path("..", current)
+        return true if File.stat(current).dev != File.stat(parent).dev
+        current = parent
+      end
+      false
+    rescue Errno::ENOENT
+      false
+    end
+
+    # Sync one Job. Returns [success, combined_output].
+    def run_job(cfg, job, dry_run: false)
+      src = job.source_path
+      tgt = job.target_path
+
+      return [false, "source not found: #{src}"] unless File.exist?(src)
+
+      FileUtils.mkdir_p(File.dirname(tgt))
+
+      args = ["rsync", "-av", "--update"]
+      args << "--dry-run" if dry_run
+      cfg.global_excludes.each { |ex| args << "--exclude=#{ex}" }
+      job.excludes.each       { |ex| args << "--exclude=#{ex}" }
+
+      if File.directory?(src)
+        args << "#{src}/" << "#{tgt}/"
+      else
+        args << src << tgt
+      end
+
+      output, status = run(args)
+      return [false, output] unless status.success?
+
+      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?
+      end
+
+      [true, output]
+    end
+
+    # Sync all jobs in a Program. Returns array of [job, success, output].
+    def run_program(cfg, program, dry_run: false)
+      program.active_jobs.map { |job| [job, *run_job(cfg, job, dry_run: dry_run)] }
+    end
+
+    def run(args)
+      require "open3"
+      stdout, stderr, status = Open3.capture3(*args)
+      [stdout + stderr, status]
+    rescue Errno::ENOENT
+      raise "command not found: #{args.first}"
+    end
+  end
+end

data/lib/twin/version.rb

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

data/lib/twin.rb

@@ -0,0 +1,7 @@
+require_relative "twin/version"
+require_relative "twin/config"
+require_relative "twin/scanner"
+require_relative "twin/sync"
+require_relative "twin/preview"
+require_relative "twin/picker"
+require_relative "twin/cli"

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mark-twin
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Ralf Hülsmann
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: twin reads sync-files (Markdown + YAML blocks) via grubber, groups them
+  by program, and runs rsync. Interactive picker uses fzf with an apex Markdown preview.
+email:
+- huelsmann@sevelen.net
+executables:
+- twin
+extensions: []
+extra_rdoc_files: []
+files:
+- ARCHITECTURE.md
+- LICENSE
+- README.md
+- bin/twin
+- lib/twin.rb
+- lib/twin/cli.rb
+- lib/twin/config.rb
+- lib/twin/picker.rb
+- lib/twin/preview.rb
+- lib/twin/scanner.rb
+- lib/twin/sync.rb
+- lib/twin/version.rb
+homepage: https://github.com/rhsev/mark-twin
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rhsev/mark-twin
+  bug_tracker_uri: https://github.com/rhsev/mark-twin/issues
+post_install_message: |2+
+
+  twin requires these external tools in your PATH:
+    grubber  https://github.com/rhsev/grubber
+    rsync    (preinstalled on macOS)
+    fzf      brew install fzf
+
+  Optional for the preview pane:
+    apex     https://github.com/ttscoff/apex
+    glow / bat as fallbacks (cat is used if none are present)
+
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Sync configuration folders between two Macs from self-documenting Markdown
+  files
+test_files: []
+...