spltty 0.1.0

data/lib/spltty_cli/commands/install.rb

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+
+require "date"
+require "erb"
+require "fileutils"
+
+module SplttyCLI
+  module Commands
+    # `spltty install` — scaffold a whole workspace in a folder: the CLI config,
+    # accounts/ with one entries + notes file per ledger, sources/INDEX.md, and a
+    # CLAUDE.md generated from the shipped template so an AI agent can drive the
+    # tracker from the first session.
+    #
+    # Interactive by default; every step can be skipped except the participants
+    # (at least one) and the default ledger (pre-filled with "expenses").
+    class Install < Dry::CLI::Command
+      desc "Set up a new expense-tracking workspace in a folder"
+
+      argument :path, required: false, desc: "Workspace directory (default: current directory)"
+
+      option :participants, aliases: ["-P"], desc: "Comma-separated participant names (e.g. Ana,Bruno)"
+      option :group,        aliases: ["-g"], desc: "Name of the shared split group (default: Both)"
+      option :split,        aliases: ["-s"], desc: "Group split as NAME:PCT,NAME:PCT (default: even)"
+      option :ledgers,      aliases: ["-l"], desc: "Comma-separated ledger names (default: expenses)"
+      option :single,                        type: :boolean, default: false,
+                                             desc: "Create ledgers as single files instead of monthly"
+      option :git,                           type: :boolean, default: nil,
+                                             desc: "Initialize a git repo (--no-git to skip)"
+      option :force,        aliases: ["-f"], type: :boolean, default: false,
+                                             desc: "Overwrite an existing workspace config"
+      option :yes,          aliases: ["-y"], type: :boolean, default: false,
+                                             desc: "Skip prompts (non-interactive)"
+
+      example [
+        "                                   # interactive, in the current directory",
+        "~/finances                         # interactive, in a new folder",
+        "~/finances -y -P Ana,Bruno         # non-interactive, one 'expenses' ledger",
+        "~/finances -y -P Ana,Bruno -s Ana:60,Bruno:40 -l HOME,TRIP",
+      ]
+
+      def call(path: nil, **opts)
+        InstallRunner.new(path, opts).run
+      rescue Prompt::Abort, Config::Error, ArgumentError => e
+        warn "spltty install: #{e.message}"
+        exit 1
+      end
+    end
+
+    # Orchestrates the install flow. Extracted from the command so it is
+    # unit-testable without going through dry-cli.
+    class InstallRunner
+      DEFAULT_LEDGER = "expenses"
+      DEFAULT_GROUP = "Both"
+
+      def initialize(path, opts)
+        @root = File.expand_path(path.to_s.empty? ? Dir.pwd : path.to_s)
+        @opts = opts
+        @interactive = !opts[:yes]
+      end
+
+      def run
+        prepare_root
+        participants = ask_participants
+        group_name, group = ask_group(participants)
+        ledgers = ask_ledgers(participants, group_name)
+        methods = ask_methods(participants, group_name || participants.first)
+
+        config = write_config(participants, group_name, group, ledgers, methods)
+        ledgers.each { |l| write_ledger(config, l) }
+        write_sources
+        claude_path = write_claude_md(participants, group_name, group, ledgers, methods)
+        maybe_git_init
+
+        reconcile(config)
+        report(ledgers, claude_path)
+      end
+
+      private
+
+      # --- prompts ------------------------------------------------------------
+
+      def prepare_root
+        existing = Config.workspace_path(@root)
+        if File.exist?(existing) && !@opts[:force]
+          raise Config::Error,
+                "#{@root} is already a spltty workspace (#{existing}) — pass --force to overwrite its config"
+        end
+
+        FileUtils.mkdir_p(@root)
+        warn "Setting up a spltty workspace in #{@root}" if @interactive
+      end
+
+      # At least one participant is required — everything else can be skipped.
+      def ask_participants
+        list = split_list(@opts[:participants])
+        while list.empty?
+          raise Prompt::Abort, "--participants is required (e.g. -P Ana,Bruno)" unless @interactive
+
+          list = split_list(Prompt.ask("Participants (comma-separated)", required: true))
+          warn "  (at least one participant is required)" if list.empty?
+        end
+        list
+      end
+
+      # The shared split group. Pointless with a single participant — skipped.
+      # Returns [name, {person => pct}] or [nil, nil] when there is none.
+      def ask_group(participants)
+        return [participants.first, nil] if participants.length < 2
+
+        name = @opts[:group]
+        name = Prompt.ask("Name for the shared split group", default: DEFAULT_GROUP) if name.nil? && @interactive
+        name = DEFAULT_GROUP if blank?(name)
+
+        split = @opts[:split]
+        default = SplttyCLI::Groups.format_split(even_split(participants))
+        split = Prompt.ask("Split for #{name}", default: default) if blank?(split) && @interactive
+        hash = blank?(split) ? even_split(participants) : SplttyCLI::Groups.parse_split(split)
+        SplttyCLI::Groups.validate(name, hash)
+        [name, hash]
+      end
+
+      # Even split, with the rounding remainder given to the first participant so
+      # the percentages always sum to 100.
+      def even_split(participants)
+        share = 100 / participants.length
+        hash = participants.to_h { |p| [p, share] }
+        hash[participants.first] += 100 - (share * participants.length)
+        hash
+      end
+
+      # One entry per ledger to create:
+      #   { name:, type:, schema:, default_responsible:, default_currency: }
+      def ask_ledgers(participants, group_name)
+        default_responsible = group_name || participants.first
+        names = split_list(@opts[:ledgers])
+        return names.map { |n| ledger_entry(n, default_responsible) } unless names.empty?
+
+        unless @interactive
+          return [ledger_entry(DEFAULT_LEDGER, default_responsible, monthly: !@opts[:single])]
+        end
+
+        ledgers = []
+        loop do
+          name = Prompt.ask("Ledger name", default: ledgers.empty? ? DEFAULT_LEDGER : nil)
+          if blank?(name)
+            break unless ledgers.empty?
+
+            name = DEFAULT_LEDGER
+          end
+
+          monthly = Prompt.confirm("  Monthly (one file per month)?", default: true)
+          multi = Prompt.confirm("  Multi-currency (extra Orig. Value + Cur. columns)?", default: false)
+          currency = multi ? Prompt.ask("  Default original currency", default: "USD").upcase : nil
+          responsible = Prompt.ask("  Default responsible", default: default_responsible)
+
+          ledgers << ledger_entry(name, responsible, monthly: monthly, currency: currency)
+          break unless Prompt.confirm("Add another ledger?", default: false)
+        end
+        ledgers
+      end
+
+      def ledger_entry(name, responsible, monthly: nil, currency: nil)
+        monthly = !@opts[:single] if monthly.nil?
+        {
+          name: name,
+          type: monthly ? "monthly" : "single",
+          schema: currency ? "montreal" : "standard",
+          default_responsible: responsible,
+          default_currency: currency,
+        }
+      end
+
+      # Optional payment-method defaults (cards). Interactive only — skipped by
+      # default and always skippable.
+      def ask_methods(participants, default_responsible)
+        return {} unless @interactive
+        return {} unless Prompt.confirm("Add a payment method (card) with defaults?", default: false)
+
+        methods = {}
+        loop do
+          name = Prompt.ask("  Payment method name (e.g. \"Visa 1234\")", required: true)
+          cfg = {}
+          slug = Prompt.ask("  Short alias for -m", default: slugify(name))
+          cfg["slug"] = slug unless blank?(slug)
+          cfg["paid_by"] = Prompt.ask("  Default paid by", default: participants.first)
+          cfg["responsible"] = Prompt.ask("  Default responsible", default: default_responsible)
+          day = Prompt.ask("  Bill payment day (1-31 or 'last')", default: "last")
+          cfg["bill_day"] = day.to_s.strip.casecmp?("last") ? "last" : day.to_i unless blank?(day)
+          methods[name] = cfg
+
+          break unless Prompt.confirm("Add another payment method?", default: false)
+        end
+        methods
+      end
+
+      def slugify(name)
+        name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+      end
+
+      # --- writing ------------------------------------------------------------
+
+      def write_config(participants, group_name, group, ledgers, methods)
+        path = Config.workspace_path(@root)
+        FileUtils.mkdir_p(File.dirname(path))
+
+        config = Config.load(path)
+        config.data["accounts_dir"] = "../accounts"
+        config.data["default_ledger"] = ledgers.first[:name]
+        config.data["date_format"] = "%Y-%m-%d"
+        config.data["participants"] = participants
+        # Merge, never replace: on a --force re-install the cards the user
+        # configured with `methods add` must survive. Same additive treatment
+        # groups and ledger entries already get below.
+        config.payment_methods.merge!(methods)
+        config.groups[group_name] = group if group
+        ledgers.each do |l|
+          entry = { "type" => l[:type], "schema" => l[:schema], "default_responsible" => l[:default_responsible] }
+          l[:type] == "monthly" ? entry["dir"] = l[:name] : entry["file"] = "#{l[:name]}.ledger.md"
+          entry["notes"] = notes_name(l)
+          entry["default_currency"] = l[:default_currency] if l[:default_currency]
+          entry["groups"] = { group_name => group } if group
+          config.ledgers[l[:name]] = entry
+        end
+        config.save
+        config
+      end
+
+      # Entries file (via Ledger.scaffold) + notes file carrying the ledger's
+      # config in its YAML header — the header is the source of truth NotesSync
+      # reconciles against config.json.
+      def write_ledger(config, ledger)
+        entry = config.ledgers[ledger[:name]]
+        today = Date.today
+        entries_path = Ledger.target_path(config, ledger[:name], entry, today)
+        unless File.exist?(entries_path)
+          Ledger.scaffold(entries_path,
+                          Ledger.title(ledger[:name], entry, today),
+                          Ledger.notes_pointer(ledger[:name], entry),
+                          Ledger.schema(entry))
+        end
+
+        notes_path = Notes.path_for(config.accounts_dir, ledger[:name], entry)
+        return if File.exist?(notes_path)
+
+        frontmatter = { "spltty" => header_for(entry, ledger) }
+        body = render("notes.md.erb",
+                      name: ledger[:name],
+                      entries: entries_label(ledger),
+                      default_responsible: ledger[:default_responsible],
+                      group_line: group_line(entry),
+                      multi_currency: ledger[:schema] == "montreal",
+                      default_currency: ledger[:default_currency])
+        FileUtils.mkdir_p(File.dirname(notes_path))
+        Notes.write(notes_path, frontmatter, body)
+      end
+
+      # The `spltty:` sub-map written into a ledger's notes header. Only the
+      # fields NotesSync manages, and only when set.
+      #
+      # `title` is deliberately omitted: Ledger.title treats it as a *format
+      # template* (`%{name} — %{month_name} %{year}`), so writing a rendered
+      # title here would freeze every future month file to this month's name.
+      def header_for(entry, ledger)
+        header = { "default_responsible" => ledger[:default_responsible] }
+        header["default_currency"] = ledger[:default_currency] if ledger[:default_currency]
+        header["groups"] = entry["groups"] if entry["groups"]
+        header
+      end
+
+      # How the notes file refers to its entries: a monthly ledger has many, so
+      # it gets a description rather than a link to one particular month.
+      def entries_label(ledger)
+        return "the `YYYY-MM.md` files in this folder" if ledger[:type] == "monthly"
+
+        file = "#{ledger[:name]}.ledger.md"
+        "[`#{file}`](#{file})"
+      end
+
+      def group_line(entry)
+        groups = entry["groups"]
+        return nil unless groups.is_a?(Hash) && !groups.empty?
+
+        groups.map { |name, hash| "`#{name}` = #{SplttyCLI::Groups.format(hash)}" }.join(", ")
+      end
+
+      def notes_name(ledger)
+        ledger[:type] == "monthly" ? "notes.md" : "#{ledger[:name]}.notes.md"
+      end
+
+      def write_sources
+        path = File.join(@root, "sources", "INDEX.md")
+        return if File.exist?(path)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, File.read(File.join(SplttyCLI::TEMPLATES_DIR, "sources-INDEX.md")))
+      end
+
+      # Render the workspace guide. An existing CLAUDE.md is never clobbered —
+      # the generated one lands next to it as CLAUDE.spltty.md instead.
+      def write_claude_md(participants, group_name, group, ledgers, methods)
+        groups = group ? { group_name => group } : {}
+        content = render("CLAUDE.md.erb",
+                         participants: participants,
+                         participants_sentence: sentence(participants),
+                         groups: groups,
+                         default_responsible: group_name || participants.first,
+                         example_split: SplttyCLI::Groups.format_split(even_split(participants)),
+                         default_ledger: ledgers.first[:name],
+                         methods: methods,
+                         ledgers: ledgers.map { |l| claude_ledger_row(l) })
+
+        path = File.join(@root, "CLAUDE.md")
+        path = File.join(@root, "CLAUDE.spltty.md") if File.exist?(path)
+        File.write(path, content)
+
+        skill = File.join(@root, ".claude", "skills", "ingest", "SKILL.md")
+        unless File.exist?(skill)
+          FileUtils.mkdir_p(File.dirname(skill))
+          File.write(skill, File.read(File.join(SplttyCLI::TEMPLATES_DIR, "skills", "ingest", "SKILL.md")))
+        end
+        path
+      end
+
+      def claude_ledger_row(ledger)
+        monthly = ledger[:type] == "monthly"
+        ledger.merge(
+          entries: monthly ? "accounts/#{ledger[:name]}/YYYY-MM.md" : "accounts/#{ledger[:name]}.ledger.md",
+          notes: monthly ? "accounts/#{ledger[:name]}/notes.md" : "accounts/#{ledger[:name]}.notes.md"
+        )
+      end
+
+      def maybe_git_init
+        return if File.exist?(File.join(@root, ".git"))
+
+        wanted = @opts[:git]
+        if wanted.nil?
+          wanted = @interactive && Prompt.confirm("Initialize a git repository here?", default: true)
+        end
+        return unless wanted
+
+        gitignore = File.join(@root, ".gitignore")
+        unless File.exist?(gitignore)
+          File.write(gitignore, File.read(File.join(SplttyCLI::TEMPLATES_DIR, "gitignore")))
+        end
+        system("git", "init", "--quiet", @root) || warn("spltty install: git init failed — skipping")
+      end
+
+      # --- finishing ----------------------------------------------------------
+
+      # Reconcile what was just written on disk with the config, so the very
+      # first `spltty list` / `totals` run is a no-op rather than a resync.
+      def reconcile(config)
+        Discovery.sync(config)
+        NotesSync.run(config)
+        config.save
+      end
+
+      def report(ledgers, claude_path)
+        puts "Created a spltty workspace in #{@root}"
+        puts "  #{Config::WORKSPACE_DIR}/#{Config::WORKSPACE_FILE}   config (participants, groups, payment methods)"
+        puts "  accounts/                #{ledgers.map { |l| l[:name] }.join(', ')}"
+        puts "  sources/INDEX.md         source tracker"
+        puts "  #{File.basename(claude_path)}                AI workflow guide"
+        puts
+        puts "Next:"
+        puts "  cd #{@root}"
+        puts "  spltty list"
+        puts "  spltty add \"First expense\" -l #{ledgers.first[:name]} -v 10.00"
+        puts "  spltty totals"
+      end
+
+      # --- helpers ------------------------------------------------------------
+
+      def render(template, **vars)
+        src = File.read(File.join(SplttyCLI::TEMPLATES_DIR, template))
+        scope = TemplateScope.new(vars)
+        ERB.new(src, trim_mode: "-").result(scope.binding_for)
+      end
+
+      def split_list(str)
+        str.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def sentence(list)
+        return list.first.to_s if list.length < 2
+
+        "#{list[0..-2].join(', ')} and #{list[-1]}"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+
+    # Plain binding holder for ERB — each key becomes a local-ish reader method,
+    # so templates read `<%= participants %>` rather than `<%= vars[:participants] %>`.
+    class TemplateScope
+      def initialize(vars)
+        vars.each { |k, v| define_singleton_method(k) { v } }
+      end
+
+      def binding_for
+        binding
+      end
+    end
+  end
+end

data/lib/spltty_cli/commands/list.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  module Commands
+    # `spltty list` — run discovery and list the known ledgers.
+    class List < Dry::CLI::Command
+      desc "List ledgers discovered under the accounts directory"
+
+      option :config,       aliases: ["-C"], desc: "Path to config.json (default: cli/config.json)"
+      option :accounts_dir, aliases: ["-A"], desc: "Override the accounts directory"
+
+      def call(**opts)
+        config = SplttyCLI.load_config(opts)
+        result = Discovery.sync(config)
+        notes = NotesSync.run(config)
+        config.save if result[:changed] || notes.values.any? { |v| !v.empty? }
+
+        if config.ledgers.empty?
+          puts "No ledgers found under #{config.accounts_dir}"
+          return
+        end
+
+        width = config.ledgers.keys.map(&:length).max
+        puts "Ledgers (accounts dir: #{config.accounts_dir}):"
+        config.ledgers.each do |name, cfg|
+          location = cfg["dir"] ? "#{cfg['dir']}/" : cfg["file"]
+          flags = cfg["missing"] ? "  [MISSING ON DISK]" : ""
+          puts format("  %-#{width}s  %-8s  %-9s  %s%s",
+                      name, cfg["type"], cfg["schema"], location, flags)
+        end
+      rescue Config::Error => e
+        warn "spltty list: #{e.message}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/spltty_cli/commands/methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SplttyCLI
+  module Commands
+    # `spltty methods` — list configured payment methods and their defaults.
+    class Methods < Dry::CLI::Command
+      desc "List configured payment methods and their defaults"
+
+      option :config, aliases: ["-C"], desc: "Path to config.json (default: cli/config.json)"
+
+      def call(**opts)
+        config = SplttyCLI.load_config(opts)
+        methods = config.payment_methods
+
+        if methods.empty?
+          puts "No payment methods configured in #{config.path}"
+          return
+        end
+
+        width = methods.keys.map(&:length).max
+        slug_width = methods.values.map { |c| (c["slug"] || "").length }.max
+        puts "Payment methods (from #{config.path}):"
+        methods.each do |name, cfg|
+          puts format("  %-#{width}s  [%-#{slug_width}s]  paid_by=%-7s responsible=%-16s bill_day=%s",
+                      name, cfg["slug"], cfg["paid_by"], cfg["responsible"], cfg["bill_day"])
+        end
+      rescue Config::Error => e
+        warn "spltty methods: #{e.message}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/spltty_cli/commands/methods_add.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SplttyCLI
+  module Commands
+    # `spltty methods add` — add or update a payment method in the config. Only
+    # the properties you pass are set; existing ones are preserved.
+    class MethodsAdd < Dry::CLI::Command
+      desc "Add or update a payment method in the config"
+
+      argument :name, required: true, desc: "Payment method name / key (e.g. \"Mastercard 3278\")"
+
+      option :slug,        aliases: ["-s"], desc: "Short alias usable with -m (e.g. mc-3278)"
+      option :paid_by,     aliases: ["-p"], desc: "Default Paid By (Thiago/Camila/...)"
+      option :responsible, aliases: ["-r"], desc: "Default Responsible (Thiago/Camila/Both/...)"
+      option :bill_day,    aliases: ["-b"], desc: "Bill payment day: a day number (1-31) or 'last'"
+      option :config,      aliases: ["-C"], desc: "Path to config.json (default: cli/config.json)"
+
+      example [
+        %("Mastercard 3278" -s mc-3278 -p Camila -r Camila -b last),
+        %("Nubank" -s nu -p Thiago -r Both -b 10),
+      ]
+
+      def call(name:, **opts)
+        config = SplttyCLI.load_config(opts)
+
+        existed = config.payment_methods.key?(name)
+        entry = (config.payment_methods[name] ||= {})
+        entry["slug"]        = opts[:slug]                    unless blank?(opts[:slug])
+        entry["paid_by"]     = opts[:paid_by]                 unless blank?(opts[:paid_by])
+        entry["responsible"] = opts[:responsible]            unless blank?(opts[:responsible])
+        entry["bill_day"]    = parse_bill_day(opts[:bill_day]) unless blank?(opts[:bill_day])
+
+        config.save
+        puts "#{existed ? 'Updated' : 'Added'} payment method #{name.inspect}: #{entry.to_json}"
+      rescue Config::Error => e
+        warn "spltty methods add: #{e.message}"
+        exit 1
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      def parse_bill_day(value)
+        s = value.to_s.strip
+        return "last" if s.casecmp?("last")
+
+        Integer(s)
+      rescue ArgumentError
+        raise Config::Error, "invalid --bill-day #{value.inspect} (use a day number 1-31 or 'last')"
+      end
+    end
+  end
+end