spltty 0.1.0

data/lib/spltty_cli/groups.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  # Split-group helpers. A group is a name -> { participant => percentage } map,
+  # e.g. { "Thiago" => 70, "Camila" => 30 }. Percentages are integers; a group
+  # should sum to 100 (validation warns, never hard-fails — Totals normalizes by
+  # the sum anyway). Groups are resolved at settlement time by `spltty totals`
+  # (see Totals): a Responsible value naming a group is split by it; anything
+  # else is treated as a person.
+  module Groups
+    module_function
+
+    # Parse "Thiago:70,Camila:30" -> { "Thiago" => 70, "Camila" => 30 }.
+    # Raises ArgumentError on malformed input.
+    def parse_split(str)
+      raise ArgumentError, "empty split" if str.nil? || str.strip.empty?
+
+      str.split(",").each_with_object({}) do |pair, h|
+        name, pct = pair.split(":", 2).map(&:strip)
+        raise ArgumentError, "bad split segment #{pair.inspect} (expected NAME:PCT)" if name.nil? || name.empty? || pct.nil?
+        raise ArgumentError, "non-integer percentage in #{pair.inspect}" unless pct.match?(/\A\d+\z/)
+
+        h[name] = pct.to_i
+      end
+    end
+
+    # Human-readable one-line form: "Thiago 70, Camila 30".
+    def format(hash)
+      hash.map { |name, pct| "#{name} #{pct}" }.join(", ")
+    end
+
+    # Round-trip form accepted by parse_split: "Thiago:70,Camila:30". Used to
+    # pre-fill prompts and examples with a value the user can edit in place.
+    def format_split(hash)
+      hash.map { |name, pct| "#{name}:#{pct}" }.join(",")
+    end
+
+    # Warn (on $stderr) when percentages are not integers or don't sum to 100.
+    # Returns true when clean, false when a warning was emitted.
+    def validate(name, hash)
+      unless hash.is_a?(Hash) && !hash.empty? && hash.values.all? { |v| v.is_a?(Integer) }
+        warn "spltty: group #{name.inspect} has non-integer or empty percentages"
+        return false
+      end
+      sum = hash.values.sum
+      if sum != 100
+        warn "spltty: group #{name.inspect} percentages sum to #{sum}, not 100"
+        return false
+      end
+      true
+    end
+
+    # Order-independent comparable key for a group definition: the name plus its
+    # participant=>pct pairs sorted by participant. Used to detect the same
+    # definition across ledgers for global promotion.
+    def canonical(name, hash)
+      [name, hash.sort_by { |k, _| k.to_s }.map { |k, v| [k.to_s, v] }]
+    end
+  end
+end

data/lib/spltty_cli/ledger.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+
+module SplttyCLI
+  # Resolve a ledger name to a concrete file path / schema / title, and scaffold
+  # the entries file (title + notes pointer + table header) when it is missing.
+  module Ledger
+    module_function
+
+    HEADERS = {
+      "standard" => [
+        "| Date       | Title | Value (R$) | Paid By | Payment Method | Responsible | Source |",
+        "|------------|-------|-----------:|---------|----------------|-------------|--------|",
+      ],
+      "montreal" => [
+        "| Date       | Title | Orig. Value | Cur. | Value (R$) | Paid By | Payment Method | Responsible | Source |",
+        "|------------|-------|------------:|------|-----------:|---------|----------------|-------------|--------|",
+      ],
+    }.freeze
+
+    def config_entry(config, name)
+      key = config.ledger_key(name)
+      key ? [key, config.ledgers[key]] : [name, nil]
+    end
+
+    def schema(entry)
+      (entry && entry["schema"]) || "standard"
+    end
+
+    def montreal?(entry)
+      schema(entry) == "montreal"
+    end
+
+    # Absolute path of the entries file for `name` on `date`.
+    def target_path(config, name, entry, date)
+      if entry && entry["type"] == "monthly"
+        dir = entry["dir"] || name
+        File.join(config.accounts_dir, dir, "#{date.strftime('%Y-%m')}.md")
+      else
+        file = (entry && entry["file"]) || "#{name}.ledger.md"
+        File.join(config.accounts_dir, file)
+      end
+    end
+
+    def title(name, entry, date)
+      monthly = entry && entry["type"] == "monthly"
+      template = (entry && entry["title"]) || (monthly ? "%{name} — %{month_name} %{year}" : "%{name}")
+      format(template, name: name, month_name: date.strftime("%B"), year: date.year)
+    end
+
+    def notes_pointer(name, entry)
+      monthly = entry && entry["type"] == "monthly"
+      (entry && entry["notes"]) || (monthly ? "notes.md" : "#{name}.notes.md")
+    end
+
+    # Create the entries file: title, notes-pointer blockquote, table header.
+    def scaffold(path, title_line, notes, schema)
+      header, separator = HEADERS.fetch(schema, HEADERS["standard"])
+      content = +"# #{title_line}\n\n"
+      content << "> Rules & conventions: [`#{notes}`](#{notes})\n\n"
+      content << header << "\n" << separator << "\n"
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+    end
+  end
+end

data/lib/spltty_cli/notes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module SplttyCLI
+  # Read / write the YAML frontmatter header of a `*.notes.md` file, and resolve
+  # a ledger's notes-file path. The header (delimited by leading `---` fences)
+  # carries ledger config under a `spltty:` sub-map; NotesSync owns that map.
+  # Any other frontmatter keys are preserved untouched on round-trip.
+  module Notes
+    module_function
+
+    FENCE = "---"
+
+    # Parse a notes file into its frontmatter + body.
+    #   { frontmatter: Hash, body: String, mtime: Time }
+    # frontmatter is {} when the file has no leading `---` block (or the file
+    # is absent). body is the content after the closing fence (or the whole
+    # file when there is no frontmatter).
+    def parse(path)
+      return { frontmatter: {}, body: "", mtime: nil } unless File.exist?(path)
+
+      raw = File.read(path)
+      mtime = File.mtime(path)
+      fm, body = split(raw)
+      { frontmatter: fm, body: body, mtime: mtime }
+    end
+
+    # Split raw file content into [frontmatter Hash, body String].
+    def split(raw)
+      lines = raw.lines
+      return [{}, raw] unless lines.first&.chomp == FENCE
+
+      close = lines[1..].index { |l| l.chomp == FENCE }
+      return [{}, raw] if close.nil?
+
+      yaml = lines[1..close].join
+      body = lines[(close + 2)..]&.join || ""
+      parsed = YAML.safe_load(yaml) || {}
+      parsed = {} unless parsed.is_a?(Hash)
+      [parsed, body]
+    end
+
+    # Write `frontmatter` + `body` back to `path`. When frontmatter is empty the
+    # file is written as body only (no fences).
+    def write(path, frontmatter, body)
+      content =
+        if frontmatter.nil? || frontmatter.empty?
+          body
+        else
+          # YAML.dump emits a leading "---\n"; append the closing fence.
+          "#{YAML.dump(frontmatter)}#{FENCE}\n#{body}"
+        end
+      File.write(path, content)
+    end
+
+    # Absolute path of a ledger's notes file, given its config entry.
+    def path_for(accounts_dir, name, entry)
+      if entry && entry["type"] == "monthly"
+        dir = entry["dir"] || name
+        File.join(accounts_dir, dir, entry["notes"] || "notes.md")
+      else
+        File.join(accounts_dir, entry&.fetch("notes", nil) || "#{name}.notes.md")
+      end
+    end
+  end
+end

data/lib/spltty_cli/notes_sync.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SplttyCLI
+  # Two-way sync of ledger config between each ledger's `*.notes.md` frontmatter
+  # (the `spltty:` sub-map) and the `ledgers` block of config.json.
+  #
+  # The notes file is the source of truth. A per-ledger `synced_at` timestamp in
+  # config is compared against the notes file's mtime to pick the direction:
+  #   * notes edited more recently (or config never synced) -> notes -> config
+  #   * config as-new-or-newer, or notes carries no managed field -> config -> notes
+  # After a config -> notes write, synced_at is stamped to the file's NEW mtime so
+  # the write does not re-trigger a notes -> config on the next run.
+  #
+  # Every managed field is optional: only keys present on the winning side are
+  # merged; an absent key is left untouched on the other side (never cleared).
+  module NotesSync
+    module_function
+
+    MANAGED = %w[title default_responsible default_currency reference groups].freeze
+
+    # Sync all ledgers in `config`. Mutates config in place (caller saves).
+    # Returns { to_config: [names], to_notes: [names], globalized: [names] }.
+    def run(config)
+      to_config = []
+      to_notes = []
+
+      config.ledgers.each do |name, entry|
+        next if entry["missing"]
+
+        path = Notes.path_for(config.accounts_dir, name, entry)
+        next unless File.exist?(path)
+
+        parsed = Notes.parse(path)
+        fm_full = parsed[:frontmatter]
+        spltty = fm_full["spltty"].is_a?(Hash) ? fm_full["spltty"] : {}
+        header_fields = MANAGED.each_with_object({}) do |k, h|
+          h[k] = spltty[k] if spltty.key?(k) && !spltty[k].nil?
+        end
+
+        s = parse_time(entry["synced_at"])
+        mtime = parsed[:mtime]
+        notes_wins = !header_fields.empty? && (s.nil? || mtime > s)
+
+        if notes_wins
+          header_fields.each { |k, v| entry[k] = v }
+          entry["synced_at"] = mtime.utc.iso8601(9)
+          to_config << name
+        elsif config_to_notes(path, entry, fm_full, spltty, parsed[:body])
+          to_notes << name
+        end
+      end
+
+      { to_config: to_config, to_notes: to_notes, globalized: globalize(config) }
+    end
+
+    # Cross-ledger promotion: any group definition (name + participants +
+    # percentages) that appears identically in >= 2 ledgers is recorded in the
+    # global config.groups. Additive only — per-ledger copies and headers are
+    # left intact, and globals are never written back into any header.
+    # Returns the list of names newly added to config.groups.
+    def globalize(config)
+      seen = Hash.new { |h, k| h[k] = { count: 0, name: nil, hash: nil } }
+      config.ledgers.each_value do |entry|
+        groups = entry["groups"]
+        next unless groups.is_a?(Hash)
+
+        groups.each do |name, hash|
+          next unless hash.is_a?(Hash)
+
+          slot = seen[Groups.canonical(name, hash)]
+          slot[:count] += 1
+          slot[:name] = name
+          slot[:hash] = hash
+        end
+      end
+
+      # Only touch config.groups when there is a shared def — avoids the lazy
+      # accessor materializing an empty "groups": {} on every sync.
+      candidates = seen.each_value.select { |slot| slot[:count] >= 2 }
+      return [] if candidates.empty?
+
+      promoted = []
+      candidates.each do |slot|
+        next if config.groups[slot[:name]] == slot[:hash]
+
+        config.groups[slot[:name]] = slot[:hash]
+        promoted << slot[:name]
+      end
+      promoted
+    end
+
+    # Write config's managed fields into the notes header. Returns true when the
+    # file content actually changed (and stamps synced_at to the new mtime).
+    def config_to_notes(path, entry, fm_full, spltty, body)
+      cfg_fields = MANAGED.each_with_object({}) do |k, h|
+        v = entry[k]
+        h[k] = v unless v.nil? || v.to_s.empty?
+      end
+      return false if cfg_fields.empty? && spltty.empty?
+
+      new_spltty = spltty.dup
+      cfg_fields.each { |k, v| new_spltty[k] = v }
+      new_fm = fm_full.dup
+      if new_spltty.empty?
+        new_fm.delete("spltty")
+      else
+        new_fm["spltty"] = new_spltty
+      end
+
+      old_raw = File.read(path)
+      new_raw = render(new_fm, body)
+      return false if new_raw == old_raw
+
+      File.write(path, new_raw)
+      entry["synced_at"] = File.mtime(path).utc.iso8601(9)
+      true
+    end
+
+    def render(frontmatter, body)
+      if frontmatter.nil? || frontmatter.empty?
+        body
+      else
+        "#{YAML.dump(frontmatter)}#{Notes::FENCE}\n#{body}"
+      end
+    end
+
+    def parse_time(str)
+      return nil if str.nil? || str.to_s.empty?
+
+      Time.iso8601(str.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/spltty_cli/prompt.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  # Minimal stdlib prompts. Prompts render on stderr so stdout stays clean for
+  # the final confirmation line; input is read from stdin.
+  module Prompt
+    class Abort < StandardError; end
+
+    module_function
+
+    # Ask for a value. Returns the entered string (or the default when the user
+    # just hits enter). With required: true, keeps asking until non-empty.
+    # At EOF (piped/no tty) it falls back to the default, or raises when a
+    # required value has no default.
+    def ask(label, default: nil, required: false)
+      loop do
+        suffix = default && !default.to_s.empty? ? " [#{default}]" : ""
+        $stderr.print "#{label}#{suffix}: "
+        raw = $stdin.gets
+        if raw.nil?
+          return default.to_s if default
+          raise Abort, "no input available for required field: #{label}" if required
+
+          return ""
+        end
+        answer = raw.strip
+        answer = default.to_s if answer.empty? && default
+        return answer unless required && answer.empty?
+
+        $stderr.puts "  (required)"
+      end
+    end
+
+    # Pick one of `options` (an array of labels). Accepts the 1-based number or
+    # the label itself (case-insensitive). Returns the 0-based index. Empty
+    # input or EOF selects `default` (which is 1-based, like what's displayed).
+    def choose(label, options, default: 1)
+      raise ArgumentError, "choose needs at least one option" if options.empty?
+
+      loop do
+        options.each_with_index { |opt, i| $stderr.puts "  #{i + 1}) #{opt}" }
+        $stderr.print "#{label} [#{default}]: "
+        raw = $stdin.gets
+        return default - 1 if raw.nil?
+
+        answer = raw.strip
+        return default - 1 if answer.empty?
+
+        index =
+          if answer.match?(/\A\d+\z/)
+            i = answer.to_i - 1
+            i if i >= 0 && i < options.length
+          else
+            options.index { |o| o.to_s.casecmp?(answer) }
+          end
+        return index if index
+
+        $stderr.puts "  (enter a number between 1 and #{options.length}, or the name)"
+      end
+    end
+
+    # Yes/no confirmation. Default answer used on empty input or EOF.
+    def confirm(label, default: true)
+      suffix = default ? "Y/n" : "y/N"
+      $stderr.print "#{label} [#{suffix}]: "
+      raw = $stdin.gets
+      return default if raw.nil?
+
+      answer = raw.strip.downcase
+      return default if answer.empty?
+
+      answer.start_with?("y")
+    end
+  end
+end

data/lib/spltty_cli/table.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  # Parse a markdown ledger table and format/append a single aligned row.
+  #
+  # Parsing (shared with the Totals reader): only lines starting with "|" are
+  # considered, the separator row is detected by its character set, the first
+  # table row is the header, and columns are addressed by header name. Writing
+  # only appends the new row — existing rows are never rewritten.
+  module Table
+    module_function
+
+    # "| a | b |" -> ["a", "b"]
+    def row_cells(line)
+      line.strip.sub(/\A\|/, "").sub(/\|\z/, "").split("|", -1).map(&:strip)
+    end
+
+    # A separator row is made up solely of -, :, and spaces (e.g. "|---|--:|").
+    def separator?(cells)
+      !cells.empty? && cells.all? { |c| c.gsub(/[:\-\s]/, "").empty? }
+    end
+
+    # Returns a hash describing the table:
+    #   :header      => array of column names
+    #   :align       => array of :left/:right per column
+    #   :widths      => array of existing max content width per column
+    #   :anchor_idx  => index (in text.split("\n", -1)) of the last "|" line
+    def parse(text)
+      lines = text.split("\n", -1)
+      header = nil
+      sep_cells = nil
+      widths = nil
+      anchor_idx = nil
+
+      lines.each_with_index do |line, i|
+        next unless line.strip.start_with?("|")
+
+        anchor_idx = i
+        cells = row_cells(line)
+
+        if separator?(cells)
+          sep_cells ||= cells if header
+          next
+        end
+
+        if header.nil?
+          header = cells
+          widths = cells.map(&:length)
+        else
+          cells.each_with_index do |c, j|
+            next if j >= widths.length
+
+            widths[j] = [widths[j], c.length].max
+          end
+        end
+      end
+
+      raise ArgumentError, "no markdown table found" if header.nil?
+
+      { header: header, align: alignments(header, sep_cells), widths: widths, anchor_idx: anchor_idx }
+    end
+
+    def alignments(header, sep_cells)
+      header.each_index.map do |j|
+        sc = sep_cells && sep_cells[j] ? sep_cells[j].strip : nil
+        if sc && sc.end_with?(":") && !sc.start_with?(":")
+          :right
+        elsif ["Value (R$)", "Orig. Value"].include?(header[j])
+          :right # fallback when no separator (e.g. freshly scaffolded file)
+        else
+          :left
+        end
+      end
+    end
+
+    # Build the markdown row string for `values` (Hash: header name => string),
+    # padded to the existing column widths so it lines up with prior rows.
+    def format_row(parsed, values)
+      cells = parsed[:header].each_index.map do |j|
+        name = parsed[:header][j]
+        content = values.fetch(name, values[name.to_sym]).to_s
+        width = [parsed[:widths][j], content.length].max
+        parsed[:align][j] == :right ? content.rjust(width) : content.ljust(width)
+      end
+      "| #{cells.join(' | ')} |"
+    end
+
+    # Insert `row` right after the last table line, preserving trailing newlines.
+    def insert_row(text, parsed, row)
+      lines = text.split("\n", -1)
+      lines.insert(parsed[:anchor_idx] + 1, row)
+      lines.join("\n")
+    end
+  end
+end