Feature: Import external rules

[davidfowl]

Summary

Allow importing merchant rules and views from external sources (local files, URLs, GitHub), enabling shared rule sets while keeping local rules in control.

Design

Import command

tally import add github:tally-community/us-merchants
tally import add https://example.com/rules/merchants.rules
tally import add ../2024/config/merchants.rules
tally import update                    # re-fetch all
tally import remove tally-community

Directory structure

config/
  merchants.rules        # Your rules (editable)
  views.rules            # Your views (editable)
  imports/
    tally-community/
      us-merchants.rules # Downloaded, immutable
    example.com/
      merchants.rules    # Downloaded, immutable

Configuration (settings.yaml)

imports:
  - source: github:tally-community/us-merchants
    priority: 10
  - source: https://example.com/rules/merchants.rules
    priority: 15
  - source: ../2024/config/merchants.rules
    priority: 40

Priority-based override

Imported rules use lower priority (e.g., 10), user rules use default (50). Local rules automatically win without editing imports:

Imported (priority 10):

[Amazon]
match: regex("AMAZON")
category: Shopping

Local override (priority 50):

[Amazon]
match: regex("AMAZON")
category: Business
tags: reimbursable

Explain shows shadowed rules

$ tally explain Amazon
Amazon → Business/Supplies
  Rule: [Amazon] (local)
  Shadowed: [Amazon] (tally-community/us-merchants)

Sources

Source	Example
GitHub	github:owner/repo or github:owner/repo/path/to/file.rules
URL	https://example.com/merchants.rules
Local file	../2024/config/merchants.rules or /path/to/shared/merchants.rules

Use cases

• Year-over-year reuse: Start 2025 by importing 2024 rules, only add what's new
• Community "best practices" merchant rules
• Crowdsourced patterns for common merchants (500+ US merchants)
• Team/company shared rules (local network or URL)
• Templates: freelancer, w2-employee, small-business
• Paystub views for specific payroll providers

Benefits

• Clean separation (your rules vs. external)
• Easy updates (just re-download, no merge conflicts)
• Immutable imports (override locally, never edit)
• No copy-paste when starting a new year
• Version pinning for GitHub: github:tally-community/us-merchants@v1.2
• Flexible sources (GitHub, URLs, local paths)