repo-tender 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6a0eecbd892c6f3ca3e1f706ac8e36c9d3b421e4354416a3aaa293224ce7926
+  data.tar.gz: 7d278c8dd24320d2c582b8e8f0fa88e36f0b7e65f777983d3c68b2f3c15e2e7b
+SHA512:
+  metadata.gz: 0d809b8db2a89cd6b0a48bb3fb2735a50b6515a27762b37f030d3a122dc72b26e43e4567c31b08b620da24a630bc7bc8796811268d3667d3e6a1af75e12f34b2
+  data.tar.gz: 176de9eb5000b95274e65111f77cd86fdad73d91616bab75d49b45d7054cdc7eaf5149cb7092b1e66f920692527305bf73f883ab76ff093b3d87d38748bdaa57

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Eric Jacobs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,257 @@
+# repo-tender 🌲
+
+[![Gem Version](https://badge.fury.io/rb/repo-tender.svg)](https://badge.fury.io/rb/repo-tender)
+
+> **Keep your local git clones forever fresh!** ヽ(•‿•)ノ✨
+
+`repo-tender` keeps your local git clones **evergreen** — clean, on their
+default branch, and recently fetched — so anything that reads them gets a
+current, trustworthy copy from your local disk instead of the network! 🪞⚡
+
+## What does "evergreen" mean? 🌿
+
+A clone is **evergreen** when all three of these hold at once:
+
+- 🧼 **Clean** — no modified, staged, untracked, or deleted files
+- 🌳 **On the default branch** — whatever the remote calls it (`main`, `trunk`,
+  `master`…); repo-tender resolves it from the remote and never assumes!
+- 🕰️ **Fresh** — fast-forwarded to the remote within your `refresh_interval`
+  (default 6h)
+
+repo-tender's whole job is to keep a tidy local mirror current, so another tool
+can clone any of them from `~/src/evergreen/...` **instantly**. 🚀
+
+**Perfect for:**
+- 🪞 A local mirror of the repos you clone from constantly
+- 🏎️ A downstream "workspace" tool that clones from local disk, not the network
+- 🐙 Keeping a whole GitHub org checked out and current
+- 🌙 Hands-off, set-and-forget background maintenance
+
+**Why repo-tender rocks:**
+- 🔒 **Never destroys your work** — dirty or diverged repos are *reported*,
+  never touched. No `reset --hard`, ever.
+- ⚡ Concurrent sync sweep powered by [socketry/async] — fibers all the way
+  down, one process, no thread soup
+- 🤖 A periodic [launchd] job syncs on a schedule while you sleep
+- 🐙 Track individual repos **or** whole GitHub orgs (expanded via `gh`)
+- 🎛️ Interactive, plain, or JSON output — pretty for you, parseable for scripts
+- 💎 Built on [dry-rb] — validated YAML config, `Result`-typed boundaries
+
+[socketry/async]: https://github.com/socketry/async
+[launchd]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
+[dry-rb]: https://dry-rb.org/
+
+## Requirements 🌍
+
+repo-tender is **macOS-only** (it schedules via launchd) and **GitHub-only**
+(it lists orgs via `gh`) — both sit behind decoupled interfaces, but those are
+today's implementations.
+
+| Tool | Version | Why |
+|------|---------|-----|
+| 🍎 macOS | — | launchd scheduling, `~/Library/LaunchAgents` |
+| [mise] | 2026.6+ | pins and provides Ruby |
+| 💎 Ruby | 4.0.5 | runtime (pinned in `mise.toml`) |
+| git | 2.54+ | the only SCM |
+| [gh] | 2.93+ | GitHub org listing (must be authenticated) |
+
+[mise]: https://mise.jdx.dev/
+[gh]: https://cli.github.com/
+
+## Installation 📦
+
+We're on RubyGems! 🎉
+
+```bash
+gem install repo-tender
+repo-tender --help
+```
+
+Prefer to hack on it? Install from source instead: 🛠️
+
+```bash
+git clone git@github.com:jetpks/repo-tender.git
+cd repo-tender
+mise install        # installs Ruby 4.0.5 per mise.toml
+bundle install
+bin/repo-tender --help
+```
+
+Make sure `gh` is logged in (otherwise org listing drops to an anonymous
+60 req/hour limit):
+
+```bash
+gh auth status
+```
+
+And you're off! 🎀
+
+## Features ✨
+
+- **The evergreen invariant** — clean · on default branch · fresh, checked per repo
+- **Safe by default** — dirty/diverged repos are reported and left byte-for-byte alone
+- **Whole-org tracking** — add `socketry` and get every repo it owns
+- **Bounded concurrency** — a fast async fan-out that won't melt your machine
+- **launchd scheduling** — `install`, `start`, `stop`, `restart`, `status`
+- **Default-branch aware** — resolves `trunk`/`master`/`main` from the remote
+- **Three output modes** — interactive TUI, plain text, or line-delimited JSON
+
+## Quick Start 🎀
+
+### Track a repo 🐙
+
+Repos are named `host/owner/name`:
+
+```bash
+repo-tender repo add github.com/ruby/ruby
+# => added: github.com/ruby/ruby
+
+repo-tender repo list
+# => github.com/ruby/ruby
+```
+
+### Track a whole org 🌐
+
+Orgs expand to their member repos at sync time (archived repos and forks are
+excluded by default):
+
+```bash
+repo-tender org add socketry              # host defaults to github.com
+repo-tender org add github.com/socketry   # equivalent, explicit host
+```
+
+### Sync everything now ⚡
+
+```bash
+repo-tender sync
+```
+
+Clones what's missing, fast-forwards what's clean-and-behind, and reports
+(never touches!) anything dirty or diverged. Scope it to one repo with
+`--repo github.com/ruby/ruby`. 🎯
+
+### Check your repos' health 🩺
+
+```bash
+repo-tender status
+```
+
+```
+REPO                            STATUS  DEFAULT_BRANCH  LAST_SYNCED_AT        LAST_FETCH_AT
+github.com/dry-rb/dry-monads    clean   main            2026-06-14T20:01:34Z  2026-06-14T20:01:33Z
+github.com/ruby/ruby            dirty   trunk           2026-06-14T20:01:36Z  2026-06-14T20:01:35Z
+```
+
+`clean` is the happy path. Anything else is repo-tender telling you a repo needs
+*your* attention — it won't touch it for you. 🔒
+
+### Schedule it & forget it 🤖
+
+Install a per-user launchd agent that runs `sync` every `refresh_interval`:
+
+```bash
+repo-tender daemon install
+repo-tender daemon status
+```
+
+macOS now syncs your repos in the background. Tear it down anytime:
+
+```bash
+repo-tender daemon stop
+repo-tender daemon uninstall
+```
+
+### Tune it 🎛️
+
+Find your config, then edit it (`repo-tender config path`):
+
+```yaml
+base_dir: ~/src/evergreen   # where clones live (pick your own!)
+refresh_interval: 90m       # "6h", "90m", "45s", "30d", or integer seconds
+concurrency: 8              # max parallel git/gh operations per run
+```
+
+```bash
+repo-tender config show   # see the effective, validated config
+```
+
+### Output for robots 🤓
+
+```bash
+repo-tender sync --json    # one JSON object per event line (12-factor!)
+repo-tender sync --plain   # one plain line per event, no color
+repo-tender status --json
+```
+
+`--no-color` and `--quiet`/`-q` work everywhere; color auto-disables off a TTY.
+
+## Command Overview 🔍
+
+**Track repos & orgs:**
+- `repo add|remove|list REF` — manage individual repos (`host/owner/name`)
+- `org add|remove|list NAME` — manage whole orgs (`name` or `host/name`)
+
+**Run & inspect:**
+- `sync [--repo REF]` — run one sync pass (optionally scoped to one repo)
+- `status` — print the per-repo evergreen status table (reads state, no network)
+- `config path|show` — show the config path, or the effective config
+
+**Schedule (launchd):**
+- `daemon install|uninstall` — write/remove the launchd agent
+- `daemon start|stop|restart` — enable / disable / run-now
+- `daemon status` — loaded? running? last exit?
+
+**Global flags:** `--plain` · `--json` · `--no-color` · `--quiet`/`-q` ·
+`--help`/`-h` · `--version`
+
+## How it works 🛠️
+
+The bits worth knowing the *why* of:
+
+- 🔒 **The cardinal rule: never lose your work.** repo-tender only ever
+  fast-forwards a *clean* repo that's strictly behind. A dirty tree, local
+  commits the remote lacks, a detached HEAD, a non-default branch — all
+  *reported* and left untouched. There is no destructive path.
+- 🤖 **A periodic launchd job, not a resident daemon.** No socket, no IPC, no
+  in-process scheduler. launchd wakes a short-lived `sync` every
+  `refresh_interval`; it fans out, writes state, and exits. (`StartInterval` +
+  `RunAtLoad`, no `KeepAlive`.)
+- 📡 **Local-first, network-last.** Each sync checks on-disk facts first — path
+  present? on default branch? clean? `.git/FETCH_HEAD` younger than the
+  interval? — and only *then* touches the network. Re-runs are cheap and
+  idempotent. ✨
+- 🗂️ **Config vs. state.** `config.yaml` is *your* durable intent (hand-edited or
+  via the CLI); `state.yaml` is machine-managed (statuses, fetch times,
+  org expansions). Splitting them keeps machine rewrites away from the file you
+  actually wrote.
+
+## Documentation 📖
+
+- **[Full Reference](docs/reference.md)** 📘 — every command, flag, config key,
+  status value, file location, and exit code
+- **[Design (PRD)](docs/prd/repo-tender.md)** 🏗️ — the full design & decisions
+- **[Builder context](AGENTS.md)** 🤝 — toolchain & conventions
+
+## Development 🧪
+
+Want to hack on it? Yay! 🎉
+
+```bash
+bundle install
+bundle exec rake test          # full minitest suite
+bundle exec standardrb         # lint / format check
+bundle exec standardrb --fix   # autofix
+```
+
+## Contributing 💝
+
+Bug reports and pull requests are welcome at
+[github.com/jetpks/repo-tender](https://github.com/jetpks/repo-tender)! 🌲
+
+## License 📄
+
+Available as open source under the terms of the [MIT License](LICENSE.txt).
+
+---
+
+Made with 💖 and a deep distrust of `reset --hard`, by Eric 🌲

data/bin/repo-tender

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby -W:no-experimental
+# frozen_string_literal: true
+
+# repo-tender CLI entrypoint. Loads the gem, hands argv to the
+# Dry::CLI registry, and translates the recorded Outcome to a
+# process exit code. See lib/repo_tender/cli.rb for the seam.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "repo_tender"
+
+RepoTender::CLI.run(ARGV, $stdout, $stderr)

data/lib/repo_tender/cli/config.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "pastel"
+require "yaml"
+require "repo_tender/cli"
+require "repo_tender/ui/mode"
+require "repo_tender/cli/options"
+
+module RepoTender
+  module CLI
+    # `config` command group: path / show.
+    module ConfigCmd
+      class Path < Dry::CLI::Command
+        include GlobalOptions
+
+        desc "Print the resolved config file path (honors $XDG_CONFIG_HOME)"
+
+        def call(plain: nil, json: nil, no_color: nil, quiet: nil, **)
+          mode = UI::Mode.resolve(
+            flags: {plain: plain, json: json, no_color: no_color, quiet: quiet},
+            env: CLI.env,
+            out: out
+          )
+          pastel = Pastel.new(enabled: mode.color)
+
+          paths = CLI.make_paths
+          out.puts pastel.cyan(paths.config_file)
+          CLI.record_outcome(Outcome.new(exit_code: 0))
+        end
+      end
+
+      class Show < Dry::CLI::Command
+        include GlobalOptions
+
+        desc "Print the effective (validated, defaults-applied) config as YAML"
+
+        def call(plain: nil, json: nil, no_color: nil, quiet: nil, **)
+          mode = UI::Mode.resolve(
+            flags: {plain: plain, json: json, no_color: no_color, quiet: quiet},
+            env: CLI.env,
+            out: out
+          )
+          pastel = Pastel.new(enabled: mode.color)
+
+          paths = CLI.make_paths
+          config = Config::Store.load(paths.config_file).success
+          # Emit via the store's own emit() so the format matches
+          # what `config.yaml` looks like on disk (stable key order
+          # per Slice 1's emit implementation). This makes
+          # `config show` a faithful round-trip preview.
+          out.puts pastel.cyan(Config::Store.emit(config.to_h).chomp)
+          CLI.record_outcome(Outcome.new(exit_code: 0))
+        end
+      end
+    end
+  end
+end
+
+# `config` is the name of both our config-store module (Config) and
+# the CLI command group. We register under a different module name
+# (ConfigCmd) to avoid the constant clash, then alias the
+# registration key as "config".
+RepoTender::CLI::Registry.register "config" do |prefix|
+  prefix.register "path", RepoTender::CLI::ConfigCmd::Path
+  prefix.register "show", RepoTender::CLI::ConfigCmd::Show
+end