mark-twin 0.1.3 → 0.3.0

checksums.yaml

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

data/ARCHITECTURE.md

@@ -9,14 +9,17 @@ sync-files (.md)
    grubber          parse Markdown, extract YAML blocks, merge frontmatter
       │
       ▼
+   Template         substitute {{tokens}} in record fields (no-op without hosts)
+      │
+      ▼
    Scanner          load_jobs → list[Job] → group(jobs) → list[Program]
       │
-      ├──▶  CLI       list / status / sync
+      ├──▶  CLI       list / status / sync / doctor
       │
       └──▶  Picker    fzf + apex preview, returns selected Program
                           │
                           ▼
-                       Sync   rsync per Job, mount check, Cmd hook
+                       Sync   rsync (or render) per Job, mount check, Cmd hook
 ```
 
 ## Package layout
@@ -24,9 +27,13 @@ sync-files (.md)
 ```
 lib/twin/
   version.rb
-  config.rb     ~/.config/twin/config.yaml loader
-  scanner.rb    Job, Program structs; grubber + stat → grouped Programs
-  sync.rb       rsync execution, mount check, post-sync hook
+  remote.rb     ssh targets: detection, reachability, batched stat, mkdir
+  template.rb   {{token}} substitution + render-file helper
+  config.rb     ~/.config/twin/config.yaml loader; host table → var_map
+  scanner.rb    Job, Program structs; grubber + template + stat → grouped Programs
+  sync.rb       rsync / render execution, mount check, post-sync hook
+  journal.rb    append-only sync journal (~/.local/state/twin/log.jsonl)
+  add.rb        `twin add` — interactive scaffolding of new sync entries
   picker.rb     fzf wrapper with apex preview
   cli.rb        subcommand dispatcher
 
@@ -39,12 +46,15 @@ test/test_pure.rb
 **Job** — one YAML block:
 
 ```
-program, path, description, active, excludes, label, source, target, cmd, sync_file,
+program, path, description, active, excludes, label, source, target, cmd,
+delete, render, render_outdated, target_path_field, sync_file,
 source_exists, target_exists, source_mtime, target_mtime, conflict
 ```
 
-`Job#status` → one of `disabled / both_missing / missing_source / missing_target /
-target_newer / in_sync / source_newer`.
+`Job#status` → one of `disabled / unreachable / both_missing / missing_source /
+missing_target / target_newer / in_sync / source_newer`. Render jobs derive status from content
+(`render_outdated`), not mtime; non-render jobs ignore those fields.
+`Job#target_path` joins `target` with `target_path_field || path`.
 
 **Program** — group of Jobs sharing a `program` name:
 
@@ -64,9 +74,20 @@ sync_dir: /path/to/sync-files
 global_excludes: [".DS_Store", ".git/"]
 apex_theme: ralf
 apex_width: 80
+
+host: mini          # which host twin runs as
+target: book        # default sync target
+hosts:
+  mini: { home: /Volumes/lightning/users/extern, git: /Volumes/lightning/Git }
+  book: { home: /Users/ralf, git: /Users/ralf/git, mount: /Volumes/ralf }
 ```
 
-Environment overrides: `TWIN_SYNC_DIR` (sync_dir), `TWIN_CONFIG` (config path).
+`Config#var_map` flattens the host table for the (`host` → `target`) pair into
+`{ "src.home" => …, "dst.home" => …, "dst.mount" => … }` — empty when no hosts
+are configured (templating inert). See the **Templating** section.
+
+Environment overrides: `TWIN_SYNC_DIR` (sync_dir), `TWIN_CONFIG` (config path),
+`TWIN_HOST` (host).
 
 ## Sync-files
 
@@ -77,6 +98,32 @@ record is self-contained.
 Multiple blocks may share the same `Program` value — these are treated as
 one logical unit by twin.
 
+## Templating
+
+Substitution sits between grubber and `build_job`, so grubber never sees
+`{{tokens}}` and stays untouched. `Scanner.load_jobs` calls
+`Template.substitute_record` on each record's path-bearing fields (`Source`,
+`Target`, `Path`, `Target-Path`, `Exclude`, `Cmd`) using `cfg.var_map`. This
+*must* run before `build_job`, which immediately `stat`s the resolved paths.
+Unknown `{{token}}` → hard error (never sync a half-rendered path).
+
+Three namespaces, one fixed meaning each:
+
+- `{{src.*}}` — the running host's own paths (read side, `Source:`).
+- `{{dst.mount}}` — where the target is mounted here (write side, `Target:`).
+- `{{dst.*}}` — the target's native paths, used in **rendered file content**.
+
+The mount/native split is the crux: a file written to `/Volumes/ralf/…` but read
+by the target machine must contain `/Users/ralf/…`. Path fields and file content
+draw from different namespaces, so a token never means two things.
+
+`{{` opens a YAML flow mapping, so templated values must be quoted in the
+sync-file (`Source: "{{src.home}}"`) — as in Ansible. Without a `hosts` table
+`var_map` is empty and substitution is a no-op.
+
+See [docs/templating-design.md](docs/templating-design.md) for the full
+rationale.
+
 ## Picker
 
 Two stages:
@@ -107,23 +154,96 @@ File argument resolution (`twin <arg>` and `--file=<arg>`):
 Unknown options (anything starting with `-` that isn't `--help`) print an
 error pointing at `twin --help` and exit 1.
 
+`twin sync` returns exit 1 when any job failed. `--quiet` suppresses output
+for successful no-op jobs (conflicts, errors and real transfers still print);
+`--skip-unavailable` skips unmounted/unreachable targets instead of aborting.
+The combination is the unattended-run mode (launchd/cron).
+
+Every non-dry-run job lands in the journal (`Journal.record`): one JSON line
+in `~/.local/state/twin/log.jsonl` (`TWIN_STATE_DIR` overrides the directory)
+with timestamp, program, path, target, `ok`, `changed`, and a truncated error
+line on failure. `twin log [-n N] [--json]` reads it back. Journal write
+failures warn once and never break a sync.
+
+`twin add <path>` (`add.rb`) scaffolds a new entry: it matches the expanded
+path against the token-substituted `Source:` frontmatter of every sync-file
+(files with no or foreign roots drop out), computes `Path:` relative to the
+chosen root, suggests excludes from a fixed list of generated/heavy dirs found
+in the source (`SUGGEST_EXCLUDES`), rejects paths the file already has a
+block for, and appends heading + prose stub + YAML block. With no covering
+sync-file it can create one (frontmatter from prompts). The pure helpers
+(`frontmatter`, `candidates`, `relative_path`, `suggest_excludes`,
+`build_block`) are unit-tested; the prompt flow reads plain stdin, so it is
+scriptable by piping answers.
+
+`twin doctor` checks required tools (grubber, rsync, fzf), optional renderers
+(apex, glow, bat), templating (host/target resolve, every `{{token}}` resolves),
+and whether all configured sync targets are mounted. Exits 1 if any required
+check fails.
+
+## Remote targets
+
+`Target: user@host:/path` (rsync notation; colon before the first slash) makes
+a job remote — `Job#remote?`. Sources stay local, twin pushes.
+
+- **Stat**: remote paths can't be `File.stat`ed, so `build_job` leaves them
+  "missing" and `Scanner.fill_remote_stats` fills them in afterwards — one
+  `ssh` round-trip per host for all its paths (`Remote.stat_paths`: paths over
+  stdin, `path\tepoch` back; BSD `stat -f %m` with GNU `stat -c %Y` fallback).
+  A failed ssh sets `target_unreachable` → status `:unreachable`; the scan
+  itself never fails on a dead host.
+- **Reachability** replaces the mount check (`Remote.reachable?`,
+  `ssh -o BatchMode=yes … true` — key auth only, never prompts).
+- **rsync** needs no changes: the target string is already in its remote
+  syntax. Parent directories are created via `ssh host mkdir -p` first.
+- **`Cmd`** still runs locally (`sh -c`); acting on the server means writing
+  an `ssh host '…'` command in the sync-file.
+- **`Render: true` + remote raises** at scan time — render reads/writes target
+  content, which twin only does on local (mounted) paths.
+
 ## Sync
 
 Before syncing:
 
-1. **Mount check** — every unique target root must be a mount point
-   (`File.stat.dev != parent.dev`). Aborts if unmounted.
+1. **Mount check** — every unique local target root must be a mount point
+   (`File.stat.dev != parent.dev`); remote targets must be ssh-reachable.
+   Aborts otherwise.
 2. **Conflict warning** — emits stderr listing jobs where the target is
    newer than the source. Continues anyway (`rsync --update` skips them).
 
-Then per Job:
+Then per Job, **rsync path** (non-render):
 
 ```
-rsync -av --update [--exclude=...]* src/ tgt/
+rsync -av --itemize-changes --update [--delete] [--exclude=...]* src/ tgt/
 ```
 
-If `Cmd` is set on the block and not in dry-run mode, the command is
-executed via `sh -c` after a successful rsync.
+`--delete` is added when the Job has `delete: true` (from `Delete: true`),
+together with `--backup --backup-dir=<target>/.twin-backup/<run-stamp>` —
+deleted and overwritten files are moved aside, not destroyed. The stamp is
+per-process, so one run shares a backup dir; rsync only creates it when it
+actually backs something up. `--exclude=.twin-backup/` protects the backup
+dir from a `Path: "."` sync deleting it. For remote targets the backup dir
+is the path part of the target (it lives on the receiving side).
+`--itemize-changes` makes change detection deterministic: `Sync.transferred?`
+matches itemize lines (`/\A[<>ch*][fdLDS]/` — `>f…`, `cd…`, `*deleting`),
+covering files, directories and deletions, with no scraping of rsync's prose.
+
+If `Cmd` is set, it runs via `sh -c` after rsync — but only when something was
+actually transferred. No-op syncs (target up to date, or target newer and
+skipped by `--update`) leave the hook silent. On failure the exit code is
+included in the output and the job is marked failed.
+
+When a job has a known conflict (`target_newer`) and nothing transferred, the
+output notes `"skipped: target is newer, source not synced"`.
+
+**Render path** (`render: true`) — `Sync.render_job`. Templates can't be
+rsync'd byte-for-byte, so instead: read source, substitute `{{dst.*}}` in the
+content, compare against the current target bytes, write only if they differ.
+`changed` drives the same `Cmd` gate. Content-hash comparison (not mtime)
+sidesteps the `--update` trap — a freshly rendered temp is always "newer".
+Render is file-only; a directory source is an error. `twin status` mirrors this:
+render-job status comes from the same content comparison (`render_outdated`),
+so a stale target with a matching mtime is still flagged `source_newer`.
 
 ## External dependencies
 

data/README.md

@@ -119,9 +119,58 @@ 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 log                     # recent journal entries (-n N, --json)
+twin doctor                  # check tools, renderers, and sync targets
 twin --help                  # show usage
 ```
 
+### Adding a sync entry
+
+`twin add <path>` scaffolds a new entry interactively, so the judgment calls
+of setting up a sync become prompts with defaults:
+
+```
+$ twin add ~/.config/fish
+sync-file: home_macbook.md  (/Users/admin → /Volumes/macbook/Users/admin)
+Program name [fish]:
+Why is this synced? (one line of prose): Shell config incl. abbreviations.
+Description (short, for listings) [fish]: Fish Shell configuration
+Exclude (comma-separated) [.git/]:
+Mirror deletions on target (Delete: true)? (y/N) [n]:
+Post-sync Cmd (empty for none):
+
+added "fish" to home_macbook.md
+Run a dry-run now? (Y/n) [y]:
+```
+
+twin matches the path against the `Source:` roots of your sync-files (asking
+which to use when several match), derives `Path:` relative to that root,
+suggests excludes for what it finds in the directory (`.git/`,
+`node_modules/`, `.venv/`, …), refuses duplicates, and appends a Markdown
+block — prose stub included. If no sync-file covers the path, it offers to
+create one (frontmatter and all), which is also the quickest way to start
+syncing to a new SSH target.
+
+Every synced job is journaled to `~/.local/state/twin/log.jsonl` (one JSON
+line per job: timestamp, program, path, outcome). `twin log` shows the recent
+history; `twin sync` exits non-zero when any job failed.
+
+### Unattended syncs
+
+For a scheduled run (launchd, cron), combine two flags:
+
+```bash
+twin sync --quiet --skip-unavailable
+```
+
+`--quiet` prints only conflicts, errors, and jobs that actually changed
+something — a no-op run is silent. `--skip-unavailable` skips targets that
+are currently unmounted or unreachable instead of aborting, so a laptop that
+isn't docked doesn't turn into an error. Combined, the run produces output
+(and a non-zero exit) only when something genuinely needs attention, which is
+exactly what launchd's stdout/stderr logging wants; the journal still records
+every job.
+
 File argument resolution:
 
 - bare name (no `/`)  → looked up by substring in `sync_dir`
@@ -145,7 +194,8 @@ global_excludes:
 # apex_code_highlight_theme: dark
 ```
 
-Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`.
+Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`, `TWIN_HOST` (which host
+twin runs as — lets one config serve both machines).
 
 ## Sync-files
 
@@ -181,12 +231,122 @@ Frontmatter fields (`Active`, `Label`, `Source`, `Target`) are merged into
 every block by grubber. Multiple blocks can share the same `Program` — twin
 groups them and treats the program as the unit of selection.
 
-The optional `Cmd` field is where the hidden trick happens: after a
-successful sync, twin runs an arbitrary shell command — typically a `curl`
-to a local automation endpoint like [mi.lan](https://github.com/rhsev/mi.lan) —
-to reload the program, run an installer, restart a service, or notify
-another machine. One config sync, one config *deployed*. See the Helix
-entry in [examples/home.md](examples/home.md).
+The optional `Cmd` field runs an arbitrary shell command after a successful
+sync — typically a `curl` to a local automation endpoint like
+[mi.lan](https://github.com/rhsev/mi.lan) to reload a program, restart a
+service, or notify another machine. The command only runs when rsync actually
+transferred bytes; no-op syncs skip it. See the Helix entry in
+[examples/home.md](examples/home.md).
+
+The optional `Delete: true` field adds `--delete` to the rsync invocation,
+so files removed from the source are also removed on the target. Useful for
+directory syncs where the target should mirror the source exactly. As a
+safety net, deleted and overwritten files are moved to a per-run backup
+directory on the target (`<target>/.twin-backup/<timestamp>/`) instead of
+being destroyed — prune it occasionally.
+
+## SSH targets
+
+`Target:` accepts remote destinations in rsync notation — `user@host:/path` or
+`host:/path`. Everything else stays the same: the YAML block, excludes,
+`Delete:`, the `Cmd` hook.
+
+````markdown
+---
+Active: 1
+Label: mini → server
+Source: /Volumes/lightning/Git/Website
+Target: ralf@server:/srv/www
+---
+
+## Website
+
+Static site, deployed straight from the build directory.
+
+```yaml
+Program: website
+Path: public
+Description: static site
+Exclude: .git/
+Cmd: ssh ralf@server 'sudo systemctl reload caddy'
+```
+````
+
+Details:
+
+- **Push only.** `Source:` stays local; twin syncs *to* the remote host.
+- **Key-based auth required.** twin probes and stats hosts with
+  `ssh -o BatchMode=yes`, which never prompts for a password. Set up an SSH
+  key (`ssh-copy-id host`) first; `twin doctor` shows whether a host is
+  reachable.
+- **Status works remotely.** `twin status` and the picker stat all remote
+  paths of a host in a single ssh round-trip (macOS and Linux targets both
+  supported). An unreachable host shows as `?` instead of failing the scan.
+- **The mount check becomes a reachability check** — sync aborts if the host
+  doesn't answer.
+- **`Cmd` runs locally**, exactly as for mounted targets. To act on the
+  server, make the command an `ssh host '…'` call (see example above).
+- **`Render: true` is not supported** for remote targets (twin would have to
+  read and write remote file contents). Render locally or keep rendered files
+  on mounted targets.
+
+## Templating
+
+Some configs differ per machine — a LaunchAgent plist that points at
+`/Volumes/lightning/…` on one Mac and `/Users/ralf/…` on another, a
+`settings.json` with a device-specific id. Those used to fall out of twin and
+get hand-maintained. Templating folds them back into one source of truth.
+
+Define a host table in `~/.config/twin/config.yaml`:
+
+```yaml
+host: mini          # which machine twin runs on
+target: book        # the machine being synced to
+
+hosts:
+  mini: { home: /Volumes/lightning/users/extern, git: /Volumes/lightning/Git }
+  book: { home: /Users/ralf, git: /Users/ralf/git, mount: /Volumes/ralf }
+```
+
+That exposes three sets of `{{tokens}}`, each with one fixed meaning:
+
+| Token | Resolves to | Use in |
+|---|---|---|
+| `{{src.home}}`, `{{src.git}}`, … | the running host's own paths | `Source:` (read side) |
+| `{{dst.mount}}` | where the target is mounted here (`/Volumes/ralf`) | `Target:` (write side) |
+| `{{dst.home}}`, `{{dst.git}}`, … | the target's *native* paths | rendered file **content** |
+
+The distinction matters: a file *written* to the mount (`/Volumes/ralf/…`) but
+*read* by the target machine must contain that machine's native paths
+(`/Users/ralf/…`). `{{dst.mount}}` and `{{dst.home}}` keep the two apart.
+
+> **Quote templated values.** `{{` at the start of a YAML value collides with
+> YAML flow-mapping syntax, so write `Source: "{{src.home}}"`, not
+> `Source: {{src.home}}` — exactly as in Ansible.
+
+`Render: true` turns a block from copy into *render*: twin reads the source as a
+template, substitutes `{{…}}` in its **content**, and writes the result only if
+it differs from the current target (so a `Cmd` hook fires only on a real change).
+`Target-Path:` overrides the target-side relative path when it differs from the
+source layout:
+
+````markdown
+## LiveSync LaunchAgent
+
+```yaml
+Program: livesync-agent
+Source: "{{src.home}}/Automation/launchd"
+Path: com.ralf.livesync.plist
+Target: "{{dst.mount}}"
+Target-Path: Library/LaunchAgents/com.ralf.livesync.plist
+Render: true
+Cmd: curl -s http://mi.lan/livesync-reload
+```
+````
+
+`twin doctor` checks that every `{{token}}` across your sync-files resolves, and
+`twin status` compares rendered output by content (not mtime). Without a `hosts`
+table, templating is inert and literal-path sync-files behave exactly as before.
 
 ## Design
 
@@ -201,3 +361,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the data model and internals.
 ```bash
 rake test
 ```
+
+---
+
+*Part of a family of plain-text tools — the [profile page](https://github.com/rhsev) has the map.*

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