agent-lock 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa831ef3bd2d74a6b65c1131ebebec51d914bd92199681d71fef99b568b75faf
-  data.tar.gz: bc0d2afc62e90a2e610f0dd4995e05e944ff00cd9a4a9ee2e59a6ad3483a463d
+  metadata.gz: d1f106a6394f81598c390390a2d83aeb051b9e22d799c23129eeed6aba0f0822
+  data.tar.gz: d31b63c4c1469eee913e33ca102dcb35f108d7b1aabb24408ec8bdd8b92958d4
 SHA512:
-  metadata.gz: d986bcb837514045683037ebaecd7ddabc4059cf00a9118c8d9998f4ec3ced0e3378ab854a1b21eaaf0a0ad4fce2473d18f8fd994287ac550f5a778ec74171da
-  data.tar.gz: 0a1925e8747601cfa147260642eb863c8c7ede69895622ee50c9c5a8c13f5c1656618e699aa80c5bdc11edc53f3728f6401cb08cf7d93bbfe3eca71b023ba736
+  metadata.gz: 8a947455256070a8bc2eb2211f63fdcc970b64e25d479ed57724ac17dbd39a28c4317fcf28465fa91b58942f4a24231af72190c34519640c905c4e04a254b38a
+  data.tar.gz: ce09be390c7cbbd93315e7b359fd30efbb53fb064d8b98b849fcb8e3fa59756fb85eec0c46b0c23d837aa87aa5d815d726c152bf4be56f44d48163eaa402310d

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [2.1.0]
+
+### Added
+
+- Help screens come from `dry-cli-help`: `alock -h` now opens with the gem's title and a description of what it does and how the two backends are chosen, lists commands in registration order, and wraps everything at 85 columns. The hand-written backend banner that used to print above dry-cli's own help is gone.
+
+### Changed
+
+- Finding a Redis now cascades: `REDIS_URL` is tried first when it is set, then `redis://127.0.0.1:6379/0`, and only when neither answers does a virgin tree default to the file store. Previously `REDIS_URL` replaced the local default rather than preceding it, so a shared Redis being down sent the tree straight to the filesystem even with one running locally. `RedisStore.url` now reports the URL that actually answered.
+
 ## [0.2.0]
 
 ### Added

data/README.md

@@ -1,9 +1,18 @@
-# Agent::Lock (v0.2.0)
+# Agent::Lock (v2.0.1)
 
 [![Ruby](https://github.com/kigster/agent-lock/actions/workflows/main.yml/badge.svg)](https://github.com/kigster/agent-lock/actions/workflows/main.yml)
 
 Advisory locks on files and folders with pluggable backends (redis and file-system provided out the box, with redis being the default if it's available locally). This locking tool is meant to be used by the coding agents that share a checkout.
 
+> [!NOTE]
+>
+> Please note that `agent-lock` is part of a three-part system: 
+>
+> 1. `agentilda` is the Ruby Gem, which is a CLI tool that creates and manages the `.plans` folder, and comes with eight or so specialized agents that take a spec.md file and work through it until it's a set of PRs open, reviewed, and passing on your CI. It does not automatically merge anything.
+> 2. [`agentilda-ai-setup`](https://kigster/agentilda-ai-setup) is the GitHub repo that's a mixture of BASH and Ruby installers. It's comes with the [`configuration.yml`](https://github.com/kigster/agentilda-ai-setup/blob/main/configuration.example.yml) file, which lists the installation commands for the coding agents you'd like to install locally, any other executables you might want (for instance, it installs `bt` — braintrust's CLI utility), and then you can list any number of Github Repos and use them to install skills, plugins, commands from them, specifying exactly which you want to install and which you want to exclude. Moreover you can specify a sub-directory of a github repo to install from.
+>
+> Together, the three repos, after installation provide you with the consistent way to replicate your `~/.agents` and `~/.claude` folders on multiple computers, and to also replicate a consistent agentic software team workflow across many projects.
+
 ## What it is
 
 `agent-lock` is a gem with one executable, `alock` (also installed as `agent-lock`). An agent runs `alock acquire <scope>` before it writes, and learns in one reply whether anybody else is working there: who, since when, and doing what. It works for separate sessions in one checkout, and for the sub-agents of a single session, which is the harder case.
@@ -316,11 +325,13 @@ Names every command and flag `alock` currently knows, since the script is genera
 | `AGENT_LOCK_MUTEX_TIMEOUT` | `15`                                    | Seconds a claim waits for the store's mutex before giving up with exit 2 |
 | `AGENT_LOCK_BACKEND`       | `redis` if one answers, else `file`     | `file` or `redis`                                                        |
 | `AGENT_LOCK_TTL_SECONDS`   | `0`                                     | Redis expiry. `0` means no TTL                                           |
-| `REDIS_URL`                | `redis://127.0.0.1:6379/0`              | Where Redis is                                                           |
+| `REDIS_URL`                | unset                                   | A shared Redis, tried before `redis://127.0.0.1:6379/0`                  |
 
 ## Backends
 
-Redis stores the same documents as the file store, and buys two things a filesystem cannot: its mutex holds across machines, and a TTL expires an abandoned lock without anybody having to reason about liveness. A tree defaults to Redis when one answers on `REDIS_URL`, and falls back to the file store, which needs nothing installed, when none does.
+Redis stores the same documents as the file store, and buys two things a filesystem cannot: its mutex holds across machines, and a TTL expires an abandoned lock without anybody having to reason about liveness. A tree defaults to Redis when one answers, and falls back to the file store, which needs nothing installed, when none does.
+
+The search for a Redis runs in a fixed order: `REDIS_URL` first, when it is set, then `redis://127.0.0.1:6379/0`. A `REDIS_URL` nobody answers on is not the end of it, since the usual reason to set one is a shared instance that is occasionally down, and a local Redis is still a better lock store than the filesystem. Only when neither answers does the tree land on the file store. `alock list` names the store in use, so it is never a guess which one you are on.
 
 ```bash
 AGENT_LOCK_BACKEND=redis alock acquire workflow/**   # force it, rather than autodetect

data/lib/agent/lock/cli.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "manager"
+require_relative "version"
 require "dry/cli"
+require "dry/cli/help"
 
 module Agent
   module Lock
@@ -15,6 +17,32 @@ module Agent
       # line, so guessing it wrong is not a cosmetic mistake.
       PROGRAM_NAME = "alock"
 
+      # What `alock -h` says before it lists the commands. Wrapped by
+      # dry-cli-help at HELP_WIDTH rather than the terminal's width, so the
+      # screen reads the same in a wide terminal, a narrow one, and a log.
+      HELP_WIDTH = 85
+
+      DESCRIPTION = <<~TEXT
+        Advisory locks for AI coding agents working concurrently in one checkout.
+        An agent claims the file or directory it is about to write, and every other
+        agent that checks sees who holds it and why. Nothing is enforced: the locks
+        work because every agent checks before it writes.
+
+        Locks live in one of two backends. Redis, when one answers on REDIS_URL or
+        on localhost:6379, holds across machines and can expire an abandoned lock.
+        The file store, used when no Redis answers, needs nothing installed. The
+        first process in a tree records which backend it chose, and every later
+        process in that tree stays on it. Set AGENT_LOCK_BACKEND to `redis` or
+        `file` to choose one yourself.
+      TEXT
+
+      Dry::CLI::Help.configure do
+        title "Agent Lock, Version #{Agent::Lock::VERSION}"
+        description DESCRIPTION
+        epilogue "Documentation: https://github.com/kigster/agent-lock"
+        width HELP_WIDTH
+      end
+
       # A registry whose commands are already bound to this launcher, so a
       # command writes to the streams it was given rather than to the process's.
       #

data/lib/agent/lock/launcher.rb

@@ -70,8 +70,6 @@ module Agent
       # @return [void] always exits, with 0 unless something said otherwise
       # rubocop:disable-next Metrics/AbcSize
       def execute!
-        backend_banner if %w[-h --help].intersect?(argv)
-
         code = 0
         Dry::CLI.new(CLI.registry_for(self)).call(arguments: argv, out: stdout, err: stderr)
       rescue SystemExit => e
@@ -93,34 +91,6 @@ module Agent
       def p(msg = "")
         stdout.puts(msg)
       end
-
-      # The two backends, ahead of dry-cli's own `--help` for each command, so
-      # a reader learns the shape of the choice before any subcommand's flags.
-      #
-      # @return [void]
-      # rubocop:disable-next Metrics/AbcSize
-      def backend_banner
-        p(bold(yellow("Agent Lock, Version #{green(Agent::Lock::VERSION)}")))
-        p
-        p(bold(blue("Usage:")))
-        p("    alock [command [ subcommand ]] [options]")
-        p
-        p(bold(blue("Description:")))
-        p("    This is a CLI utility aimed at the agents working concurrently in the same")
-        p("    environment, sharing filesystem, worktrees, etc. Agent Lock allows fine-grained")
-        p("    and effective locking, and can use multiple backends to store and maintain locks.")
-        p
-        p(cyan("    • Redis-Based Locking"))
-        p("      This mechanism uses locally running Redis instance to coordinate access to shared")
-        p("      resources (default, if Redis is available and accessible).")
-        p
-        p(cyan("    • File System Locking"))
-        p("      This mechanism uses file system locks to coordinate access to shared resources.")
-        p
-        p("    You can set the environment variable #{yellow("AGENT_LOCK_BACKEND")} to either")
-        p("    'redis' or 'file' to override the default.")
-        p
-      end
     end
   end
 end

data/lib/agent/lock/store/redis_store.rb

@@ -20,10 +20,14 @@ module Agent
       # markdown document either way.
       #
       # Picked with AGENT_LOCK_BACKEND=redis, or by default when one answers on
-      # REDIS_URL. See Store's moduledoc for how that default is decided.
+      # REDIS_URL, or failing that on the local default. See Store's moduledoc
+      # for how that default is decided.
       class RedisStore
         NAMESPACE = "agent-lock"
 
+        # Tried after REDIS_URL, or alone when it is unset.
+        LOCAL_URL = "redis://127.0.0.1:6379/0"
+
         # How long the store mutex outlives a holder that died holding it. A
         # claim's critical section is a SCAN and one SET, so ten seconds is
         # somebody gone, not somebody busy.
@@ -206,15 +210,59 @@ module Agent
         end
 
         class << self
-          def url = ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0")
+          # The URL of the Redis actually in use, once one has answered, or
+          # the first one that will be tried before then.
+          #
+          # @return [String]
+          def url = @url || candidate_urls.first
+
+          # Where to look, in order: `REDIS_URL` when set, then the local
+          # default. A `REDIS_URL` that nobody answers on is not the end of
+          # the search, because the usual reason it is set is a shared
+          # instance that is sometimes down, and a local one is still better
+          # than falling all the way back to the filesystem.
+          #
+          # @return [Array<String>]
+          def candidate_urls
+            configured = ENV["REDIS_URL"].to_s.strip
+            [configured.empty? ? nil : configured, LOCAL_URL].compact.uniq
+          end
 
+          # Tries each candidate URL in turn and keeps the first that answers.
+          #
           # @return Array[RedisClient,NilClass,Exception] the client if it could be created,
-          # or the error that prevented it
+          # or the error that prevented it (the last one tried)
           def create_client
-            @client ||= ::Redis.new(url: url).tap do |client|
-              _version = client.info["redis_version"]
+            return [@client, nil] if @client
+
+            error = nil
+            candidate_urls.each do |candidate|
+              client, error = connect(candidate)
+              next unless client
+
+              @url = candidate
+              @client = client
+              return [@client, nil]
             end
-            [@client, nil]
+            [nil, error]
+          end
+
+          # Drops the memoized client, so the next `create_client` probes again.
+          #
+          # @return [void]
+          def reset!
+            @client = nil
+            @url = nil
+          end
+
+          private
+
+          # @param candidate [String]
+          # @return Array[RedisClient,NilClass,Exception]
+          def connect(candidate)
+            client = ::Redis.new(url: candidate)
+            client.info["redis_version"]
+            [client, nil]
           rescue Redis::CannotConnectError, Redis::BaseError, Errno::ECONNREFUSED, SocketError => e
             [nil, e]
           end

data/lib/agent/lock/store.rb

@@ -12,7 +12,8 @@ module Agent
     #
     # AGENT_LOCK_BACKEND wins when set. Otherwise a tree that already has a
     # marker keeps using it. A virgin tree defaults to Redis when one answers
-    # locally, file when none does.
+    # on REDIS_URL or, failing that, on the local default; file when neither
+    # does.
     #
     # That default is still never a runtime auto-*switch*: once a marker
     # exists, every later process in that tree is bound to it regardless of
@@ -90,7 +91,8 @@ module Agent
 
       def marker_path(tree) = File.join(tree.store_dir, MARKER)
 
-      # @return [String] "redis" when one answers on REDIS_URL, "file" otherwise
+      # @return [String] "redis" when one answers on REDIS_URL or, failing
+      #   that, on RedisStore::LOCAL_URL; "file" when neither does
       def default_backend
         local_redis_available? ? "redis" : "file"
       end

data/lib/agent/lock/version.rb

@@ -2,6 +2,6 @@
 
 module Agent
   module Lock
-    VERSION = "2.0.0"
+    VERSION = "2.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-lock
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -93,15 +93,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 'This compact ruby gem is purely CI utility: it''s meant to be used with
-  the team of AI agentsexecuting along the plan you approved. Using worktrees and
-  parallelism it''s easy to 10x the speed of develpoment of software even compared
-  to a single agent working on it. Plus each agent can specialize. With that, these
-  agents need a shared locking mechanism to ensure they are not working on the same
-  directory, same worktree, and soon. This gem is exaclty that tool. The gem distributed
-  as ''agent-lock'', and offers the shortened binary called ''alock'' (although ''agent-lock''
-  works as well). The best way to understand the gem is to install and run it with
-  ''alock --help''. Furthermore, each subcommand has an additional help.'
+description: 'This compact ruby gem is purely CLI utility: it''s meant to be used
+  by a team of AI agentsexecuting along one or more the plans in a given repo. Using
+  worktrees and parallelism it''s easy to 10x the speed of develpoment of software
+  development compared to even a single agent working on it. Plus each agent can specialize.
+  Such agents require globsl shared locking mechanism to ensure they are not working
+  on the same directory, or the same files in same worktree. That is exactly what
+  this gem does. The CLI binary you invoke is called ''alock''which comes with sub-command
+  ''completion'' which you can load for BASH or ZSH. However, you are not very likely
+  going toinvoke this gem directly. It''s used by an Agentic Workflow gem ''agentilda''
+  to protect shared resources. To try the entire system, it''s recommended to download
+  the repo https://github.com/kigster/agentilda-ai-setup which both installs the two
+  gems, and offers a configuration file that installs a set of coding agents, skills,
+  plugins, commands, from various guthub folders, or via running commands, and so
+  on. In other words the repo''s purpose is to ensure your agentic setup is identical
+  from machine to machine, and by modifying the config file you can pick and choose
+  your skills, your AGENT.md/CLAUDE.md file and so on.'
 email:
 - kigster@gmail.com
 executables:
@@ -175,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Advisory locks to prevent race conditions and general mayhem when multiple
   AI agents unknowinly modify the same souce three.