mark-twin 0.2.0 → 0.4.0

data/bin/twin

@@ -1,5 +1,10 @@
 #!/usr/bin/env ruby
 
+# Sync-files are UTF-8 regardless of the environment's locale — without this,
+# a launchd/cron context (no LANG) reads them as US-ASCII and chokes on "→".
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
 require "twin"

data/lib/twin/add.rb

@@ -0,0 +1,177 @@
+require "yaml"
+
+require_relative "template"
+
+module Twin
+  # `twin add <path>` — guided scaffolding of a new sync entry. Turns the
+  # judgment calls of the "add a sync" recipe (which sync-file? which Path?
+  # what to exclude? deploy hook?) into prompts with sensible defaults, then
+  # appends a Markdown block to the chosen sync-file.
+  module Add
+    module_function
+
+    # Directories that are usually machine-generated or heavy — offered as
+    # exclude defaults when present in the source directory.
+    SUGGEST_EXCLUDES = %w[.git node_modules .venv __pycache__ dist build target].freeze
+
+    # ── pure helpers (unit-tested) ────────────────────────────────────────────
+
+    # Frontmatter of a sync-file as a Hash (Source/Target token-substituted),
+    # or nil when the file has none / it isn't a Hash.
+    def frontmatter(file, vars = {})
+      text = File.read(file)
+      return nil unless text.start_with?("---\n")
+      body = text[4..].split(/^---\s*$/, 2).first
+      data = begin
+        YAML.safe_load(body.to_s)
+      rescue Psych::SyntaxError
+        nil
+      end
+      return nil unless data.is_a?(Hash)
+      %w[Source Target].each do |k|
+        next unless data[k].is_a?(String)
+        data[k] = Twin::Template.substitute(data[k], vars, context: File.basename(file))
+      end
+      data
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Sync-files in dir whose Source is an ancestor of path.
+    # Returns [[file, frontmatter], …].
+    def candidates(dir, path, vars = {})
+      Dir.glob(File.join(dir, "*.md")).sort.filter_map do |f|
+        fm = frontmatter(f, vars)
+        next unless fm && fm["Source"].is_a?(String) && !fm["Source"].empty?
+        root = File.expand_path(fm["Source"])
+        next unless path == root || path.start_with?(root + "/")
+        [f, fm]
+      end
+    end
+
+    def relative_path(root, path)
+      path == root ? "." : path[(root.length + 1)..]
+    end
+
+    def suggest_excludes(path)
+      return [] unless File.directory?(path)
+      SUGGEST_EXCLUDES.filter_map do |e|
+        full = File.join(path, e)
+        next unless File.exist?(full)
+        File.directory?(full) ? "#{e}/" : e
+      end
+    end
+
+    def build_block(program:, path:, description: "", excludes: [], delete: false, cmd: "", prose: "")
+      yaml = ["Program: #{program}", "Path: #{path}"]
+      yaml << "Description: #{description}"        unless description.empty?
+      yaml << "Exclude: #{excludes.join(',')}"     unless excludes.empty?
+      yaml << "Delete: true"                       if delete
+      yaml << "Cmd: #{cmd}"                        unless cmd.empty?
+      prose = "TODO: document why this path is synced." if prose.empty?
+      "\n## #{program}\n\n#{prose}\n\n```yaml\n#{yaml.join("\n")}\n```\n"
+    end
+
+    def frontmatter_text(source:, target:, label: "")
+      lines = ["---", "Active: 1"]
+      lines << "Label: #{label}" unless label.empty?
+      lines << "Source: #{source}" << "Target: #{target}" << "---" << ""
+      lines.join("\n")
+    end
+
+    # ── interactive flow ──────────────────────────────────────────────────────
+
+    # Returns {program:, file:, dry_run:} on success (dry_run: whether the
+    # user asked for one), nil when nothing was written.
+    def run(cfg, args)
+      raw = args.first
+      raise "usage: twin add <path>" if raw.nil? || raw.empty?
+      path = File.expand_path(raw)
+      raise "not found: #{path}" unless File.exist?(path)
+
+      vars = cfg.var_map
+      picked = pick_sync_file(cfg, path, vars)
+      return nil unless picked
+      file, fm = picked
+
+      root = File.expand_path(fm["Source"])
+      rel  = relative_path(root, path)
+
+      if File.exist?(file) && File.read(file).match?(/^Path:\s*#{Regexp.escape(rel)}\s*$/)
+        raise "#{File.basename(file)} already has a block with Path: #{rel}"
+      end
+
+      program = ask("Program name", File.basename(path))
+      prose   = ask("Why is this synced? (one line of prose)")
+      desc    = ask("Description (short, for listings)", program)
+      excl    = ask("Exclude (comma-separated)", suggest_excludes(path).join(","))
+                  .split(",").map(&:strip).reject(&:empty?)
+      delete  = yes?(ask("Mirror deletions on target (Delete: true)? (y/N)", "n"))
+      cmd     = ask("Post-sync Cmd (empty for none)")
+
+      block = build_block(program: program, path: rel, description: desc,
+                          excludes: excl, delete: delete, cmd: cmd, prose: prose)
+      File.open(file, "a") { |f| f.write(block) }
+
+      puts "\nadded #{program.inspect} to #{File.basename(file)}"
+      puts "  #{File.join(root, rel)}  →  #{File.join(fm['Target'].to_s, rel)}"
+
+      dry = yes?(ask("Run a dry-run now? (Y/n)", "y"))
+      { program: program, file: file, dry_run: dry }
+    end
+
+    # Choose (or create) the sync-file covering path.
+    # Returns [file, frontmatter] or nil.
+    def pick_sync_file(cfg, path, vars)
+      cands = candidates(cfg.sync_dir, path, vars)
+      case cands.size
+      when 0 then offer_new_sync_file(cfg, path, vars)
+      when 1
+        file, fm = cands.first
+        puts "sync-file: #{File.basename(file)}  (#{fm['Source']} → #{fm['Target']})"
+        cands.first
+      else
+        puts "multiple sync-files cover #{path}:"
+        cands.each_with_index do |(f, fm), i|
+          puts "  #{i + 1}) #{File.basename(f)}  (#{fm['Source']} → #{fm['Target']})"
+        end
+        n = ask("Which one?", "1").to_i
+        cands[n - 1] or raise "invalid choice: #{n}"
+      end
+    end
+
+    def offer_new_sync_file(cfg, path, vars)
+      puts "no sync-file in #{cfg.sync_dir} covers #{path}"
+      return nil unless yes?(ask("Create a new sync-file? (y/N)", "n"))
+
+      name = ask("File name", "#{File.basename(path).sub(/\A\./, '')}.md")
+      name += ".md" unless name.end_with?(".md")
+      file = File.join(cfg.sync_dir, name)
+      raise "already exists: #{file}" if File.exist?(file)
+
+      source = ask("Source base on this machine", File.dirname(path))
+      target = ask("Target base (mount path or user@host:/path)")
+      raise "Target is required" if target.empty?
+      label  = ask("Label (e.g. mini → server)")
+
+      File.write(file, frontmatter_text(source: source, target: target, label: label))
+      puts "created #{File.basename(file)}"
+      fm = { "Source" => source, "Target" => target }
+      %w[Source Target].each do |k|
+        fm[k] = Twin::Template.substitute(fm[k], vars, context: name)
+      end
+      [file, fm]
+    end
+
+    def ask(prompt, default = "")
+      print default.empty? ? "#{prompt}: " : "#{prompt} [#{default}]: "
+      $stdout.flush
+      ans = $stdin.gets
+      raise "aborted (stdin closed)" if ans.nil?
+      ans = ans.strip
+      ans.empty? ? default : ans
+    end
+
+    def yes?(answer) = answer.match?(/\Ay/i)
+  end
+end

data/lib/twin/cli.rb

@@ -6,6 +6,8 @@ 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
@@ -22,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]
+                    [--force] [--skip-conflicts]
+        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
 
@@ -29,6 +35,12 @@ module Twin
         bare name (no /)  → matched by substring against sync-file names
         contains /        → resolved as path; file or directory both work
 
+      TARGET-SIDE CHANGES:
+        Before syncing, twin looks for files the target changed more recently
+        AND whose content differs, then asks once for the whole program.
+        --force           overwrite them without asking (for automation)
+        --skip-conflicts  leave them alone, sync everything else
+
       CONFIG:
         ~/.config/twin/config.yaml
         TWIN_SYNC_DIR  overrides sync_dir
@@ -46,6 +58,8 @@ 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
@@ -137,10 +151,13 @@ 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}"
           puts "      dst #{tgt}"
+          # Named, not hidden: these belong to the target on purpose.
+          puts "      own #{j.owned.join(', ')}" unless j.owned.nil? || j.owned.empty?
         end
       end
     end
@@ -156,46 +173,179 @@ 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],
+                  force: opts[:force], skip_conflicts: opts[:skip_conflicts])
+      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,
+                  force: false, skip_conflicts: 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?
-        warn "warning: target is newer than source:"
-        conflicts.each { |j| warn "  ! #{j.path}" }
-        warn "continuing sync (--update skips newer files on target)."
-      end
+      # Decide about target-side changes BEFORE the first byte moves: a partly
+      # applied program is worse than none at all. resolve_conflicts returns
+      # false when the run must not happen.
+      force = resolve_conflicts(cfg, jobs, dry_run: dry_run, quiet: quiet,
+                                force: force, skip_conflicts: skip_conflicts)
+      return false if force == :abort
 
-      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, force: force)
+        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
+
+    # Settle what happens to files the target changed more recently, before any
+    # job runs. Returns true (overwrite them), false (leave them, --update keeps
+    # them) or :abort (sync nothing at all).
+    #
+    # The mtime pre-filter on each Job is coarse and fires often; only files
+    # whose content really differs reach the prompt. A prompt that cries wolf
+    # gets answered without reading it.
+    def resolve_conflicts(cfg, jobs, dry_run:, quiet:, force:, skip_conflicts:)
+      return true  if force
+      return false if skip_conflicts || dry_run
+
+      conflicts = jobs.flat_map { |j| Twin::Conflict.detect(cfg, j) }
+      return false if conflicts.empty?
+
+      report_conflicts(conflicts)
+
+      unless $stdin.tty? && $stdout.tty?
+        warn ""
+        warn "abort: target has changes of its own and there is no terminal to ask."
+        warn "       re-run with --force to overwrite them, or --skip-conflicts to keep them."
+        return :abort
+      end
+
+      loop do
+        print "\noverwrite these on the target and sync? [y]es / [d]iff / [n]o (abort) "
+        $stdout.flush
+        case $stdin.gets&.strip&.downcase
+        when "y", "yes"  then return true
+        when "n", "no", "", nil then puts "aborted — nothing was synced."; return :abort
+        when "d", "diff" then show_diffs(conflicts)
+        else puts "please answer y, d or n."
+        end
+      end
+    end
+
+    def report_conflicts(conflicts)
+      warn "target has changed since the last sync — #{conflicts.size} file(s) differ:"
+      conflicts.each do |c|
+        delta = c.age_delta
+        age   = delta ? " (target #{format_age(delta)} newer)" : ""
+        warn "  ! #{c.job.path == c.rel ? c.rel : File.join(c.job.path, c.rel)}#{age}"
+      end
+      warn "syncing would replace them with the source version."
+    end
+
+    def show_diffs(conflicts)
+      conflicts.each do |c|
+        puts
+        puts "── #{c.rel} " + "─" * [0, 60 - c.rel.length].max
+        puts Twin::Conflict.diff(c)
+      end
+    end
+
+    def format_age(seconds)
+      s = seconds.to_i.abs
+      return "#{s}s"           if s < 90
+      return "#{s / 60}m"      if s < 5400
+      return "#{s / 3600}h"    if s < 172_800
+      "#{s / 86_400}d"
+    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 ─────────────────────────────────────────────────────────────────
@@ -252,7 +402,15 @@ module Twin
           puts "  (no programs loaded)"
         else
           targets.each do |tgt|
-            if Twin::Sync.mounted?(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)"
@@ -287,13 +445,18 @@ 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, force: false, skip_conflicts: 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("--force")           { opts[:force] = true }
+        o.on("--skip-conflicts")  { opts[:skip_conflicts] = true }
         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/conflict.rb

@@ -0,0 +1,143 @@
+require "digest"
+
+require_relative "remote"
+
+module Twin
+  # Finding out which files on the target would be silently skipped by rsync's
+  # --update, and whether that actually matters.
+  #
+  # `Job#conflict` is no help here. It compares the mtime of the job's own path,
+  # and for a directory job that is the directory's mtime — which says nothing
+  # about the files inside it. Worse, it is wrong in exactly the case that
+  # matters: editing a file in place leaves its directory's mtime untouched, and
+  # `rsync -a` equalises directory mtimes on every run anyway. A hand-edit on
+  # the target is therefore invisible to it.
+  #
+  # So we ask rsync, which has the answer already and knows its own matching
+  # rules better than any reimplementation would:
+  #
+  #   1. Which files does --update hold back?
+  #      Dry-run twice, once with --update and once without. Everything the
+  #      second run would transfer but the first would not is exactly the set
+  #      --update protects.
+  #
+  #   2. Of those, which differ in content?
+  #      Only these are worth asking about. A file that is merely newer — same
+  #      bytes, later timestamp — is noise, and noise is what turns a prompt
+  #      into a reflex. Sync both sides of a tree in either order and you get
+  #      dozens of them.
+  #
+  # The first dry-run is also the cheap exit: when a forced run would move
+  # nothing, the job is fully in sync and the second run is skipped. That is the
+  # common case, so a quiet sync costs one extra stat-walk per job and no more.
+  module Conflict
+    # One file the target owns more recently than the source, with content that
+    # actually differs. `same_content` is nil when it could not be determined
+    # (remote targets) — treated as a conflict, because guessing in the other
+    # direction would overwrite work.
+    Entry = Struct.new(:job, :rel, :source_path, :target_path,
+                       :source_mtime, :target_mtime, keyword_init: true) do
+      def age_delta
+        return nil unless source_mtime && target_mtime
+        target_mtime - source_mtime
+      end
+    end
+
+    # rsync --itemize-changes line → relative path. Change lines start with an
+    # update type and a file type (">f.st...... lib/foo.rb"); "*deleting" and
+    # the surrounding prose do not match.
+    ITEMIZE_LINE = /\A[<>ch][fdLDS]\S*\s+(.+?)\s*\z/
+
+    module_function
+
+    # Real conflicts for one job, in the order rsync reports them.
+    # Empty when --update holds nothing back, or holds back only identical files.
+    def detect(cfg, job)
+      # Render jobs compare by content already and never use --update.
+      return [] if job.render
+      return [] unless job.source_exists && job.target_exists
+
+      held_back_paths(cfg, job).filter_map { |rel| entry_for(job, rel) }
+    end
+
+    # Relative paths that --update would skip: (would transfer forced) minus
+    # (would transfer normally).
+    def held_back_paths(cfg, job)
+      forced = itemized_paths(Twin::Sync.rsync_args(cfg, job, dry_run: true, force: true))
+      return [] if forced.empty?   # nothing to move at all — no need to ask rsync twice
+
+      normal = itemized_paths(Twin::Sync.rsync_args(cfg, job, dry_run: true, force: false))
+      forced - normal
+    end
+
+    def itemized_paths(args)
+      output, status = Twin::Sync.run(args)
+      return [] unless status.success?
+      output.lines.filter_map do |line|
+        m = ITEMIZE_LINE.match(line)
+        next unless m
+        rel = m[1]
+        next if rel == "./" || rel.end_with?("/")   # directories carry no content
+        rel
+      end
+    end
+
+    # Build an Entry unless source and target hold the same bytes.
+    def entry_for(job, rel)
+      src = resolve(job.source_path, rel)
+      tgt = resolve(job.target_path, rel)
+
+      # Remote targets can't be read here; report them rather than assume.
+      unless job.remote?
+        return nil if same_content?(src, tgt)
+      end
+
+      Entry.new(
+        job: job, rel: rel, source_path: src, target_path: tgt,
+        source_mtime: mtime(src), target_mtime: job.remote? ? nil : mtime(tgt),
+      )
+    end
+
+    # A job path may be a single file — rsync then itemizes its basename, and
+    # the job path is already the full path.
+    def resolve(base, rel)
+      File.directory?(base) ? File.join(base, rel) : base
+    end
+
+    def same_content?(a, b)
+      return false unless File.file?(a) && File.file?(b)
+      return false unless File.size(a) == File.size(b)
+      digest(a) == digest(b)
+    rescue Errno::ENOENT, Errno::EACCES
+      false
+    end
+
+    def digest(path) = Digest::SHA256.file(path).hexdigest
+
+    def mtime(path)
+      File.mtime(path)
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+
+    # Unified diff for one entry, or a short note when it can't be produced.
+    def diff(entry)
+      return "  (remote target — no diff available)" if entry.job.remote?
+      return "  (binary or unreadable)" unless text?(entry.source_path) && text?(entry.target_path)
+
+      out, _status = Twin::Sync.run([
+        "diff", "-u",
+        "--label", "target (#{entry.target_path})", entry.target_path,
+        "--label", "source (#{entry.source_path})", entry.source_path,
+      ])
+      out.empty? ? "  (no textual difference)" : out
+    end
+
+    # Cheap heuristic: a NUL byte in the first 8 KiB means binary.
+    def text?(path)
+      File.open(path, "rb") { |f| !f.read(8192).to_s.include?("\0") }
+    rescue Errno::ENOENT, Errno::EACCES
+      false
+    end
+  end
+end

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