agent-lock 0.2.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13449d302065507190249f6bcf9cea27e2e4ce283a1aa422213122951826d78e
-  data.tar.gz: db759d6540ea353eda999c77eb02d2b6d8d5887f86e8fad52036ef93774124b6
+  metadata.gz: d1f106a6394f81598c390390a2d83aeb051b9e22d799c23129eeed6aba0f0822
+  data.tar.gz: d31b63c4c1469eee913e33ca102dcb35f108d7b1aabb24408ec8bdd8b92958d4
 SHA512:
-  metadata.gz: 2f56d58d5250a8dda75cae4f6a39b741f2186864bf91296954b6996e36b9cf9984413ddb19c92d96570f2286bfc0b88feea58d1ade5e7fcbb2a8e595e74450b5
-  data.tar.gz: 9421c3c1397eedbd49fbe3ac735aec9f649ef7938bf4f0d16e2bb70368278e5ff60caf5dc291356e43adef931f23f34c3632f120ed8731a78c182be2b9e2ce7e
+  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,8 +1,17 @@
-# 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 file locks for coding agents that share a checkout.
+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
 
@@ -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 = "0.2.1"
+    VERSION = "2.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-lock
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -29,14 +29,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: dry-cli-help
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: dry-cli-ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement
@@ -65,10 +93,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 'A CLI an agent runs before it writes: claim a path or a glob, see who
-  holds one, record progress inside the lock, and pick the work back up after a crash.
-  Identity belongs to the session rather than the process, so a lock taken by one
-  command can be released by the next.'
+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:
@@ -78,8 +118,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/CLAUDE.md"
-- ".envrc"
-- ".rubocop_todo.yml"
 - ".ruby-version"
 - AGENTS.md
 - CHANGELOG.md
@@ -144,7 +182,8 @@ 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 for the several coding agents that end up in one checkout
+summary: Advisory locks to prevent race conditions and general mayhem when multiple
+  AI agents unknowinly modify the same souce three.
 test_files: []

data/.envrc

@@ -1,2 +0,0 @@
-PATH_add bin
-PATH_add exe

data/.rubocop_todo.yml

@@ -1,90 +0,0 @@
-# This configuration was generated by
-# `rubocop --auto-gen-config --no-auto-gen-timestamp`
-# using RuboCop version 1.91.0.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 1
-Gemspec/RequiredRubyVersion:
-  Exclude:
-    - 'agent-lock.gemspec'
-
-# Offense count: 3
-# Configuration parameters: Prefixes, AllowedPatterns.
-# Prefixes: when, with, without
-RSpec/ContextWording:
-  Exclude:
-    - 'spec/agent/lock/tree_spec.rb'
-    - 'spec/support/aruba.rb'
-    - 'spec/support/checkout.rb'
-
-# Offense count: 3
-# Configuration parameters: IgnoredMetadata.
-RSpec/DescribeClass:
-  Exclude:
-    - '**/spec/features/**/*'
-    - '**/spec/requests/**/*'
-    - '**/spec/routing/**/*'
-    - '**/spec/system/**/*'
-    - '**/spec/views/**/*'
-    - 'spec/agent/lock/concurrency_spec.rb'
-    - 'spec/agent/lock/loading_spec.rb'
-    - 'spec/agent/lock/manager_spec.rb'
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
-# SupportedStyles: described_class, explicit
-RSpec/DescribedClass:
-  Exclude:
-    - 'spec/agent/lock/manager_spec.rb'
-
-# Offense count: 46
-# Configuration parameters: CountAsOne.
-RSpec/ExampleLength:
-  Max: 20
-
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-RSpec/IncludeExamples:
-  Exclude:
-    - 'spec/agent/lock/concurrency_spec.rb'
-
-# Offense count: 5
-# Configuration parameters: AssignmentOnly.
-RSpec/InstanceVariable:
-  Exclude:
-    - 'spec/agent/lock/tree_spec.rb'
-    - 'spec/support/checkout.rb'
-
-# Offense count: 2
-RSpec/LeakyLocalVariable:
-  Exclude:
-    - 'spec/agent/lock/loading_spec.rb'
-
-# Offense count: 2
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: have_received, receive
-RSpec/MessageSpies:
-  Exclude:
-    - 'spec/agent/lock/freeze_spec.rb'
-    - 'spec/agent/lock/store_spec.rb'
-
-# Offense count: 1
-RSpec/MultipleDescribes:
-  Exclude:
-    - 'spec/agent/lock/manager_spec.rb'
-
-# Offense count: 6
-RSpec/MultipleExpectations:
-  Max: 2
-
-# Offense count: 1
-# Configuration parameters: AllowedClasses.
-Style/OneClassPerFile:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/agent/lock/cli.rb'