mark-twin 0.1.3 → 0.3.0

data/lib/twin/cli.rb

@@ -1,10 +1,13 @@
 require "optparse"
 require "json"
 require "set"
+require "time"  # Time#iso8601 for --json output
 
 require_relative "config"
 require_relative "scanner"
 require_relative "sync"
+require_relative "journal"
+require_relative "add"
 require_relative "picker"
 
 module Twin
@@ -21,6 +24,10 @@ 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]
+                    [--quiet] [--skip-unavailable]
+        twin add <path>            scaffold a new sync entry for a local path
+        twin log    [-n N] [--json]  recent journal entries (default 20)
+        twin doctor                check tools, renderers, and sync targets
         twin --help                show this message
 
       FILE ARGUMENT:
@@ -44,6 +51,9 @@ 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 "add"      then cmd_add(cfg, argv.drop(1))
+      when "log"      then cmd_log(argv.drop(1))
+      when "doctor"   then cmd_doctor(cfg)
       when "-h", "--help", "help"
         puts USAGE
       when /\A-/
@@ -134,6 +144,7 @@ module Twin
         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)"
+          tgt = "(unreachable)" if j.target_unreachable
           conflict = j.conflict ? (tty ? "  #{Picker.colorize(:target_newer, "!")}" : "  !") : ""
           puts "    #{j.path}#{conflict}"
           puts "      src #{src}"
@@ -153,31 +164,40 @@ module Twin
       end
 
       if programs.empty?
-        puts "no matching programs"
+        puts "no matching programs" unless opts[:quiet]
         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)
+      results = programs.map do |p|
+        sync_jobs(cfg, p, p.active_jobs,
+                  dry_run: opts[:dry_run], quiet: opts[:quiet],
+                  skip_unavailable: opts[:skip_unavailable])
+      end
+      exit 1 unless results.all?
     end
 
-    def sync_jobs(cfg, program, jobs, dry_run: false)
+    # Sync the given jobs. Returns true when every attempted job succeeded.
+    # quiet:            print only conflicts, errors, and jobs that changed something
+    # skip_unavailable: skip jobs whose target is unmounted/unreachable instead of aborting
+    def sync_jobs(cfg, program, jobs, dry_run: false, quiet: false, skip_unavailable: 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"
+      return true if jobs.empty?
+
+      # one availability check per unique target root:
+      # local targets must be mounted volumes, remote ones reachable via ssh
+      availability = {}
+      jobs.each { |j| availability[j.target] ||= target_availability(j) }
+      jobs, unavailable = jobs.partition { |j| availability[j.target] == :ok }
+
+      unavailable.map { |j| availability[j.target] }.uniq.each do |reason|
+        if skip_unavailable
+          puts "skipped: #{reason}" unless quiet
+        else
+          warn "abort: #{reason}"
           exit 1
         end
-        checked << j.target
       end
+      return true if jobs.empty?
 
       conflicts = jobs.select(&:conflict)
       unless conflicts.empty?
@@ -186,13 +206,157 @@ module Twin
         warn "continuing sync (--update skips newer files on target)."
       end
 
-      puts "→ #{program.name}"
+      header_printed = false
+      all_ok = true
       jobs.each do |job|
-        success, output = Twin::Sync.run_job(cfg, job, dry_run: dry_run)
+        success, output, transferred = Twin::Sync.run_job(cfg, job, dry_run: dry_run)
+        Twin::Journal.record(job, success: success, transferred: transferred, output: output) unless dry_run
+        all_ok &&= success
+        next if quiet && success && !transferred
+
+        unless header_printed
+          puts "→ #{program.name}"
+          header_printed = true
+        end
         puts "  • #{job.path}"
         puts output.gsub(/^/, "    ") if output && !output.strip.empty?
         warn "  error syncing #{job.path}" unless success
       end
+      all_ok
+    end
+
+    # :ok, or a human-readable reason the target can't be synced right now.
+    def target_availability(job)
+      if job.remote?
+        host, = Twin::Remote.split(job.target)
+        return :ok if Twin::Remote.reachable?(host)
+        "#{host} is not reachable via ssh"
+      else
+        return :ok if Twin::Sync.mounted?(job.target)
+        "#{job.target} is not a mounted volume"
+      end
+    end
+
+    # ── add ────────────────────────────────────────────────────────────────────
+
+    def cmd_add(cfg, args)
+      result = Twin::Add.run(cfg, args)
+      return unless result && result[:dry_run]
+      cmd_sync(cfg, ["-p", result[:program],
+                     "--file=#{File.basename(result[:file])}", "--dry-run"])
+    end
+
+    # ── log ────────────────────────────────────────────────────────────────────
+
+    def cmd_log(args)
+      n = 20
+      json = false
+      OptionParser.new do |o|
+        o.on("-n N", Integer) { |v| n = v }
+        o.on("--json")        { json = true }
+      end.parse!(args)
+
+      entries = Twin::Journal.tail(n)
+      if json
+        puts JSON.pretty_generate(entries)
+        return
+      end
+      if entries.empty?
+        puts "journal is empty (#{Twin::Journal.log_path})"
+        return
+      end
+
+      tty = $stdout.tty?
+      entries.each do |e|
+        ts   = Time.parse(e["ts"]).strftime("%Y-%m-%d %H:%M:%S")
+        mark = e["ok"] ? "✓" : "✗"
+        mark = Picker.colorize(e["ok"] ? :in_sync : :both_missing, mark) if tty
+        note = e["ok"] ? (e["changed"] ? "changed" : "no-op") : "error: #{e["error"]}"
+        puts "#{ts}  #{mark}  #{e["program"]}  #{e["path"]}  (#{note})"
+      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::Remote.remote?(tgt)
+              host, = Twin::Remote.split(tgt)
+              if Twin::Remote.reachable?(host)
+                puts "  ✓  #{tgt}  (ssh)"
+              else
+                puts "  ✗  #{tgt}  (ssh: #{host} not reachable)"
+                ok = false
+              end
+            elsif 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 ─────────────────────────────────────────────────────────
@@ -209,13 +373,16 @@ module Twin
     end
 
     def parse_sync_opts(args)
-      opts = { show_all: false, label: nil, file: nil, pattern: nil, dry_run: false }
+      opts = { show_all: false, label: nil, file: nil, pattern: nil, dry_run: false,
+               quiet: false, skip_unavailable: 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 }
+        o.on("-q", "--quiet")  { opts[:quiet] = true }
+        o.on("--skip-unavailable") { opts[:skip_unavailable] = true }
       end.parse!(args)
       opts
     end

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/journal.rb

@@ -0,0 +1,49 @@
+require "json"
+require "fileutils"
+require "time"
+
+module Twin
+  # Append-only sync journal: one JSON line per synced job in
+  # ~/.local/state/twin/log.jsonl. Answers "did yesterday's sync actually
+  # run, and what did it do?" — and stays machine-readable (jq/grubber).
+  # Journal failures never break a sync; they degrade to a warning.
+  module Journal
+    module_function
+
+    def state_dir
+      ENV["TWIN_STATE_DIR"] || File.join(Dir.home, ".local", "state", "twin")
+    end
+
+    def log_path = File.join(state_dir, "log.jsonl")
+
+    # Record one job result. Dry-runs are not journaled.
+    def record(job, success:, transferred:, output: nil)
+      entry = {
+        ts:      Time.now.iso8601,
+        program: job.program,
+        path:    job.path,
+        target:  job.target,
+        ok:      success,
+        changed: transferred,
+      }
+      unless success
+        entry[:error] = output.to_s.lines.map(&:strip).reject(&:empty?).last.to_s[0, 200]
+      end
+      FileUtils.mkdir_p(state_dir)
+      File.open(log_path, "a") { |f| f.puts(JSON.generate(entry)) }
+    rescue SystemCallError => e
+      warn "journal: #{e.message}" unless @warned
+      @warned = true
+    end
+
+    # Last n entries, oldest first. Unparseable lines are skipped.
+    def tail(n)
+      return [] unless File.exist?(log_path)
+      File.readlines(log_path).last(n).filter_map do |line|
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/twin/picker.rb

@@ -17,6 +17,7 @@ module Twin
       missing_target: "!",
       missing_source: "!",
       both_missing:   "✗",
+      unreachable:    "?",
       disabled:       "·",
     }.freeze
 
@@ -27,6 +28,7 @@ module Twin
       missing_target: "\e[31m",   # red
       missing_source: "\e[31m",   # red
       both_missing:   "\e[31m",   # red
+      unreachable:    "\e[31m",   # red
       disabled:       "\e[2m",    # dim
     }.freeze
 

data/lib/twin/remote.rb

@@ -0,0 +1,72 @@
+require "open3"
+
+module Twin
+  # Remote (ssh) targets, written exactly as rsync understands them:
+  # "user@host:/path" or "host:/path". A target counts as remote when a colon
+  # appears before the first slash. Sources stay local — twin pushes.
+  module Remote
+    module_function
+
+    SSH_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=5"].freeze
+
+    def remote?(target)
+      %r{\A[^/]+:}.match?(target.to_s)
+    end
+
+    # "user@host:/path" → ["user@host", "/path"]
+    def split(target)
+      host, path = target.to_s.split(":", 2)
+      [host, path.to_s]
+    end
+
+    # Non-interactive reachability probe (BatchMode: never asks for a password).
+    def reachable?(host)
+      system("ssh", *SSH_OPTS, host, "true", out: File::NULL, err: File::NULL)
+    end
+
+    # Stat many paths in one ssh round-trip. Paths go over stdin (one per
+    # line), the remote loop answers "path<TAB>epoch" or "path<TAB>-" for
+    # missing ones. Tries BSD stat first, then GNU — covers macOS and Linux.
+    # Returns {path => Time or nil-if-missing}, or nil when ssh itself failed.
+    STAT_SCRIPT = <<~SH.freeze
+      while IFS= read -r p; do
+        if [ -e "$p" ]; then
+          printf '%s\t%s\n' "$p" "$(stat -f %m -- "$p" 2>/dev/null || stat -c %Y -- "$p")"
+        else
+          printf '%s\t-\n' "$p"
+        fi
+      done
+    SH
+
+    def stat_paths(host, paths)
+      return {} if paths.empty?
+      out, _err, status = Open3.capture3(
+        "ssh", *SSH_OPTS, host, STAT_SCRIPT,
+        stdin_data: paths.join("\n") + "\n"
+      )
+      return nil unless status.success?
+
+      result = {}
+      out.each_line do |line|
+        path, mtime = line.chomp.split("\t", 2)
+        next unless path && mtime
+        result[path] = mtime == "-" ? nil : Time.at(mtime.to_i)
+      end
+      result
+    rescue Errno::ENOENT
+      nil # ssh not installed
+    end
+
+    # Create a directory on the remote side (mkdir -p equivalent).
+    def mkdir_p(host, dir)
+      _out, _err, status = Open3.capture3("ssh", *SSH_OPTS, host, "mkdir", "-p", shellesc(dir))
+      status.success?
+    end
+
+    # Escape one argument for the remote shell (ssh joins args with spaces and
+    # hands the string to a shell — local exec-style arrays don't protect it).
+    def shellesc(s)
+      "'" + s.gsub("'", "'\\\\''") + "'"
+    end
+  end
+end

data/lib/twin/scanner.rb

@@ -1,22 +1,30 @@
 require "json"
 require "open3"
 
+require_relative "remote"
+
 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,
+    :target_unreachable,
     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 remote?     = Twin::Remote.remote?(target)
 
     def status
       return :disabled if active != 1
+      return :unreachable if target_unreachable
       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
@@ -38,7 +46,7 @@ module Twin
     # 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]
+      %i[unreachable both_missing missing_source missing_target target_newer source_newer disabled in_sync]
         .find { |s| states.include?(s) } || :in_sync
     end
 
@@ -65,7 +73,36 @@ 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
+      jobs = 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
+      fill_remote_stats(jobs)
+      jobs
+    end
+
+    # Remote targets can't be stat'ed locally — batch them into one ssh
+    # round-trip per host. A failed ssh marks the jobs unreachable instead
+    # of aborting the scan (local jobs stay usable).
+    def fill_remote_stats(jobs)
+      jobs.select { |j| j.remote? && j.active == 1 }
+          .group_by { |j| Twin::Remote.split(j.target).first }
+          .each do |host, host_jobs|
+        stats = Twin::Remote.stat_paths(host, host_jobs.map { |j| Twin::Remote.split(j.target_path).last })
+        host_jobs.each do |j|
+          rpath = Twin::Remote.split(j.target_path).last
+          if stats.nil?
+            j.target_unreachable = true
+            next
+          end
+          mtime = stats[rpath]
+          j.target_exists = !mtime.nil?
+          j.target_mtime  = mtime
+          j.conflict      = j.source_exists && mtime && j.source_mtime &&
+                            mtime - j.source_mtime >= 60
+        end
+      end
     end
 
     def load_programs(cfg, file: nil, label: nil, show_all: false)
@@ -98,38 +135,57 @@ 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?)
+      remote   = Twin::Remote.remote?(target)
+
+      if render && remote
+        raise "#{r["Program"]}: Render is not supported for remote targets (#{target})"
+      end
 
       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)
+      # Remote targets are stat'ed in one batched ssh call after all jobs are
+      # built (fill_remote_stats) — until then they read as missing.
+      tgt_exists, tgt_mtime = remote ? [false, nil] : 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,
+        target_unreachable: false,
       )
     end
 
@@ -139,5 +195,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