agent-lock 0.2.1

data/justfile

@@ -0,0 +1,127 @@
+# Tell 'just' to run bash, source our setup script, then execute the recipe
+set shell := ["bash", "-c"]
+
+version := `grep VERSION lib/agent/lock/version.rb | awk '{print $3}' | tr -d '"' | tr -d '\n'`
+repo := 'git@github.com:kigster/agent-lock.git'
+
+rbenv := 'eval "$(rbenv init - bash 2>/dev/null || true)"; bundle exec '
+
+# 1Password secret reference for the RubyGems TOTP, and the full path to `op`
+# because a recipe does not inherit an interactive shell's PATH.
+# The account is NOT named here: it is a private 1Password address and this
+# file is public. `op` reads it from OP_ACCOUNT, exported by the ecosystem
+# root's .envrc, which lives outside every repo. Two accounts are
+# registered and only one holds the open-source-repos vault, so without
+# OP_ACCOUNT the read can resolve against the wrong one, return nothing,
+# and publish silently falls back to prompting mid-release.
+op := '/opt/homebrew/bin/op'
+otp_ref := 'op://open-source-repos/ruby-gems/one-time password?attribute=otp'
+
+gem_name := 'agent-lock'
+gem_file := 'pkg/' + gem_name + '-' + version + '.gem'
+gem_url := 'https://rubygems.org/gems/' + gem_name
+
+[no-exit-message]
+recipes:
+    just --choose
+
+# Sync all dependencies
+install:
+    bin/setup
+
+build: install
+
+# standardrb
+lint:
+    {{ rbenv }} standardrb
+
+# Fix style with standardrb, then format the markdown
+format:
+    bundle exec rubocop -a
+    bundle exec rubocop --auto-gen-config
+    /usr/bin/find . -name '*.md' -exec mdformat --wrap no {} \; -print
+
+update-workflow:
+    bundle exec tilda docs -o docs/WORKFLOW.md
+
+# Run all the tests
+test *args:
+    export ENVIRONMENT=test; {{ rbenv }} rspec {{ args }}
+
+# Run tests with coverage
+test-coverage *args:
+    export ENVIRONMENT=test; export COVERAGE=true; {{ rbenv }} rspec {{ args }}
+
+ci: lint test-coverage
+
+alias check-all := ci
+
+clean:
+    #!/usr/bin/env bash
+    @find . -name .DS_Store -delete -print || true
+    @rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+lefthook:
+    {{ rbenv }} lefthook run pre-commit --all-files
+
+# Print current gem version
+version:
+    @echo "{{ version }}"
+
+# Clobber
+clobber:
+    {{ rbenv }} rake clobber
+
+# Generate documentation
+doc:
+    #!/usr/bin/env bash
+    {{ rbenv }} rake doc
+
+# `gem push` rather than `rake release`: release also guards the tree, tags and
+# pushes git — which `just release` does deliberately and separately — and it
+# gives no way to pass a 2FA code, so it always stopped to prompt.
+#
+# The code comes from 1Password unless one is passed in:
+#
+#   just publish            # read the code from 1Password
+#   just publish 123456     # use this code
+#
+# `just publish-all` in agent-lock-tools passes one, because a TOTP is single-use:
+# four gems reading the same 30-second window would have the second push
+# rejected as a replay.
+#
+# Build the .gem and push it to RubyGems, non-interactively
+publish otp="": build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    eval "$(rbenv init - bash 2>/dev/null || true)"
+
+    mkdir -p pkg
+    gem build {{ gem_name }}.gemspec --output "{{ gem_file }}"
+
+    # `|| true` is load-bearing: under `set -e` a failed `op read` — not signed
+    # in to 1Password, item renamed, op not installed — would abort the recipe
+    # before the prompting fallback below could run.
+    otp="{{ otp }}"
+    [[ -n "${otp}" ]] || otp=$({{ op }} read "{{ otp_ref }}" 2>/dev/null || true)
+
+    if [[ -n "${otp}" ]]; then
+        {{ rbenv }} gem push "{{ gem_file }}" --otp "${otp}"
+    else
+        echo "rubygems: no OTP available — gem push will prompt if 2FA is required."
+        {{ rbenv }} gem push "{{ gem_file }}" --no-document
+    fi
+
+    # Only reachable when the push succeeded: `set -e` aborts the recipe on a
+    # non-zero `gem push`, so the page never opens for a release that failed.
+    echo "published {{ gem_name }} {{ version }} → {{ gem_url }}"
+    open "{{ gem_url }}" 2>/dev/null || xdg-open "{{ gem_url }}" 2>/dev/null || true
+
+# Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
+release:
+    git fetch --tags
+    git tag -f "v{{ version }}"
+    git push -f --tags
+    gh release delete -y "v{{ version }}" --repo {{ repo }} 2>/dev/null || true
+    gh release create "v{{ version }}" --generate-notes --repo {{ repo }}

data/lib/agent/lock/cli/commands/acquire.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Claim a scope, or find out who has it.
+        class Acquire < Base
+          desc "Claim a path or glob; exits 1 if somebody else holds it"
+
+          argument :scope, required: true, desc: "A path, a directory, or a glob such as 'workflow/**'"
+          argument :intent, required: false, desc: "What you are about to do, for whoever reads the lock"
+
+          option :enforce, type: :boolean, default: false,
+                           desc: "Also make the matched files unwritable (macOS)"
+          option :force, type: :boolean, default: false,
+                         desc: "Allow --enforce on a very wide scope"
+
+          example [
+            "workflow/** 'rewriting the installer'",
+            "lib/agent/lock/cli.rb 'adding the json flag'",
+            "'**' 'a migration that touches everything'"
+          ]
+
+          # @param scope [String]
+          # @param intent [String, nil]
+          # @param options [Hash]
+          # @return [Manager::Result]
+          def call(scope:, intent: nil, **options)
+            manager = manager(options[:dir])
+            result = manager.acquire(
+              scope, intent: intent || "unspecified",
+                     enforce: options[:enforce], force: options[:force]
+            )
+
+            report(result, manager.stale_minutes)
+            finish(result)
+          end
+
+          private
+
+          # @param result [Manager::Result]
+          # @param stale_minutes [Integer]
+          def report(result, stale_minutes)
+            case result.status
+            when :acquired then report_acquired(result)
+            when :already_mine then say("ALREADY YOURS #{result.record.scope}")
+            when :held
+              warn_("REFUSED, do not write here")
+              report_held(result.records, stale_minutes: stale_minutes)
+            when :interrupted then report_interrupted(result.record)
+            when :parent_scope then report_parent_scope(result.record)
+            end
+          end
+
+          # A refusal no amount of waiting fixes, so it says what will work
+          # instead. Locks are keyed by scope, which makes the parent's record
+          # the very one this child would have to write.
+          #
+          # @param record [Record] the parent's lock on this exact scope
+          def report_parent_scope(record)
+            warn_("REFUSED: #{record.scope} is your parent's (#{record.agent_id}) whole claim; " \
+                  "claim a narrower scope inside it")
+          end
+
+          def report_acquired(result)
+            record = result.record
+            say("ACQUIRED #{record.scope}  (holder: #{record.agent_id})")
+            say("FROZEN   #{record.frozen_paths.size} file(s)") if record.frozen_paths.any?
+            warn_(result.message) if result.message
+          end
+
+          # An orphan is somebody's unfinished work, so the two ways out of it
+          # are spelled out rather than left to be looked up.
+          #
+          # @param record [Record] the orphaned lock on this exact scope
+          def report_interrupted(record)
+            warn_("INTERRUPTED WORK on #{record.scope}, left by #{record.agent_id}")
+            advise_interrupted(record)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/base.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require_relative "../../manager"
+
+require "json"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # What every command shares: the launcher it prints through, the
+        # manager it delegates to, and the wording of a held lock.
+        #
+        # Nothing here calls `puts` or `exit`. Output goes to the launcher's
+        # streams and the exit code is handed back to it, which is what lets
+        # the whole CLI run inside the test process.
+        class Base < Dry::CLI::Command
+          # Inherited by every command, so `--dir` works everywhere without
+          # each one restating it.
+          def self.inherited(subclass)
+            super
+            subclass.option :dir, type: :string, default: ".",
+                                  desc: "Work as if run from this directory"
+          end
+
+          attr_reader :launcher
+
+          # @param launcher [Launcher]
+          def initialize(launcher = nil)
+            super()
+            @launcher = launcher
+          end
+
+          private
+
+          def stdout = launcher.stdout
+
+          def stderr = launcher.stderr
+
+          # What to call this CLI in a hint, so the command it suggests is
+          # one the user can paste back: `alock` for somebody who typed `alock`.
+          #
+          # @return [String]
+          def program = launcher.program
+
+          # @param dir [String]
+          # @return [Manager]
+          def manager(dir) = Manager.new(tree: Tree.for(dir || "."))
+
+          # @param text [String]
+          def say(text) = stdout.puts(text)
+
+          # STDOUT is flushed first. An agent harness reads both streams down
+          # one pipe, where STDOUT is block-buffered and STDERR is not, and
+          # without the flush every hint arrives ahead of the record it is
+          # about.
+          #
+          # @param text [String]
+          def warn_(text)
+            stdout.flush
+            stderr.puts(text)
+          end
+
+          # @param result [Manager::Result]
+          def finish(result)
+            launcher.exit_code = result.code
+            result
+          end
+
+          # The one message worth getting right: an agent that hits a lock
+          # should learn who has it, since when, and what they are doing, so it
+          # can decide whether to wait or to work somewhere else. A stale
+          # holder changes that decision, from waiting to asking somebody, so
+          # it is said outright rather than left to be worked out from a date.
+          #
+          # @param records [Array<Record>]
+          # @param stale_minutes [Integer] Manager#stale_minutes
+          def report_held(records, stale_minutes:)
+            records.each do |record|
+              warn_(["HELD  #{record.scope}  by #{record.agent_id}  since #{record.created_at}",
+                     tag_for(record, stale_minutes)].compact.join("  "))
+              warn_("      intent: #{record.intent}") unless record.intent.empty?
+              warn_("      frozen: #{record.frozen_paths.size} file(s)") if record.frozen_paths.any?
+              warn_stale(record, stale_minutes) if record.stale?(stale_minutes)
+            end
+          end
+
+          # One line per record, tagged, so that a line lifted out by `grep`
+          # still says whether it is a claim in good standing.
+          #
+          # @param records [Array<Record>]
+          # @param json [Boolean]
+          # @param stale_minutes [Integer] Manager#stale_minutes
+          def report_records(records, json:, stale_minutes:)
+            return say(JSON.pretty_generate(records.map { |record| as_json(record, stale_minutes) })) if json
+
+            records.each do |record|
+              say([record.scope, record.agent_id, record.created_at, tag_for(record, stale_minutes)].compact.join("\t"))
+              say("  #{record.intent}") unless record.intent.empty?
+            end
+          end
+
+          # The two ways out of an interrupted lock, spelled out rather than
+          # left to be looked up, since each throws away something different.
+          #
+          # @param record [Record] an orphaned lock
+          def advise_interrupted(record)
+            warn_("  #{program} resume #{record.scope}   # take it back, notes and all")
+            warn_("  #{program} break #{record.scope}    # throw it away and start over")
+          end
+
+          # @param record [Record]
+          # @param stale_minutes [Integer]
+          # @return [String, nil] INTERRUPTED, STALE, or nil for a claim in good standing
+          def tag_for(record, stale_minutes)
+            return "INTERRUPTED" if record.orphaned?
+
+            "STALE" if record.stale?(stale_minutes)
+          end
+
+          # A stale holder is not a dead one: a holder that died on this machine
+          # is reaped on its own, so this one is most likely still running and
+          # merely quiet. Breaking it is a decision somebody announces, never a
+          # default.
+          #
+          # @param record [Record]
+          # @param stale_minutes [Integer]
+          def warn_stale(record, stale_minutes)
+            warn_("      stale: untouched for over #{stale_minutes} minutes; ask its holder, " \
+                  "or announce it before `#{program} break #{record.scope}`")
+          end
+
+          # `stale` is computed, not stored, so it is added here; `status`
+          # already says whether a record is interrupted.
+          #
+          # @param record [Record]
+          # @param stale_minutes [Integer]
+          # @return [Hash]
+          def as_json(record, stale_minutes)
+            Record::FIELDS.to_h { |field| [field, record.public_send(field)] }
+                          .merge(intent: record.intent, stale: record.stale?(stale_minutes))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/break.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Take a lock away from whoever holds it.
+        #
+        # Deliberately blunt and deliberately loud: an expired lock is reaped
+        # on its own, so reaching for this means overruling a holder that still
+        # looks alive. Whoever runs it owns the consequence.
+        class Break < Base
+          desc "Steal a lock; announce it first"
+
+          argument :scope, required: true, desc: "The path or glob to take"
+
+          def call(scope:, **options)
+            result = manager(options[:dir]).break_lock(scope)
+
+            if result.status == :not_found
+              say("NOT LOCKED #{scope}")
+            else
+              warn_("BREAKING #{result.record.scope}, held by #{result.record.agent_id}")
+              warn_("  intent: #{result.record.intent}") unless result.record.intent.empty?
+              say("Broken. You are responsible for having announced this first.")
+            end
+
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Ask before writing. Exits 1 when anything overlapping is held, so a
+        # shell script can gate on it without parsing anything.
+        class Check < Base
+          desc "Say who holds a path; exits 1 if it is held"
+
+          argument :scope, required: true, desc: "A path, a directory, or a glob"
+
+          option :json, type: :boolean, default: false, desc: "Machine-readable output"
+
+          example ["workflow/**", "lib/agent/lock/cli.rb --json"]
+
+          # @param scope [String]
+          # @param options [Hash]
+          # @return [Manager::Result]
+          def call(scope:, **options)
+            manager = manager(options[:dir])
+            result = manager.check(scope)
+            report(result, scope, json: options[:json], stale_minutes: manager.stale_minutes)
+            finish(result)
+          end
+
+          private
+
+          # @param result [Manager::Result]
+          # @param scope [String] as the user typed it
+          # @param json [Boolean]
+          # @param stale_minutes [Integer]
+          def report(result, scope, json:, stale_minutes:)
+            case result.status
+            when :free then say(json ? "[]" : "FREE #{scope}")
+            when :mine
+              # Held, but by you: safe to write, and worth saying which of your
+              # own locks covers it rather than a bare "free".
+              report_records(result.records, json: json, stale_minutes: stale_minutes)
+              say("YOURS #{result.record.scope}") unless json
+            when :held
+              if json
+                report_records(result.records, json: true, stale_minutes: stale_minutes)
+              else
+                report_held(result.records, stale_minutes: stale_minutes)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/completion.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "dry/cli/autocomplete/command"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # `alock completion bash|zsh`, from dry-cli-autocomplete, with the two
+        # things that gem's command cannot do for us restated here.
+        #
+        # It writes to `$stdout` directly, which the in-process launcher can
+        # neither capture nor redirect, and it binds a registry by way of
+        # `Class.new`, which is exactly where dry-cli clears an inherited
+        # `desc` and `example`. Both belong upstream; until then, here.
+        class Completion < Dry::CLI::Autocomplete::Command
+          desc "Print a shell completion script for bash or zsh"
+
+          # Spelled out rather than taken from $PROGRAM_NAME, which under a
+          # test runner names the runner, and which upstream reads at load
+          # time anyway.
+          example [
+            "bash > \"$(brew --prefix)/etc/bash_completion.d/alock\"",
+            "zsh  > \"${fpath[1]}/_alo\""
+          ]
+
+          # Binding a registry subclasses this command, and dry-cli's
+          # `inherited` hook starts every subclass with no description and no
+          # examples. Arguments and options survive it; those two do not, so
+          # they are copied across by hand.
+          #
+          # @param registry [Dry::CLI::Registry]
+          # @return [Class]
+          def self.[](registry, program_name: nil)
+            super.tap do |bound|
+              bound.desc(description)
+              bound.example(*examples)
+            end
+          end
+
+          private
+
+          # dry-cli hands every command the stream it should be writing to.
+          # The command upstream ignores it; this one does not.
+          def out = @out || $stdout
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/list.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Everything in this tree's store, worktree siblings included, since
+        # they share one `.git` and therefore one set of locks.
+        #
+        # Live claims and interrupted work are listed apart. An orphan blocks
+        # nobody, so counting it as held told a reader the tree was busier
+        # than it was, and gave them no way to see which locks were real.
+        class List < Base
+          desc "Every live lock, and any interrupted work"
+
+          option :json, type: :boolean, default: false, desc: "Machine-readable output"
+
+          example ["", "--json"]
+
+          # @param options [Hash]
+          # @return [Manager::Result]
+          def call(**options)
+            manager = manager(options[:dir])
+            result = manager.list
+
+            if options[:json]
+              report_records(result.records, json: true, stale_minutes: manager.stale_minutes)
+            else
+              report_listing(result.records, manager.stale_minutes)
+            end
+
+            finish(result)
+          end
+
+          private
+
+          # @param records [Array<Record>]
+          # @param stale_minutes [Integer]
+          def report_listing(records, stale_minutes)
+            held, interrupted = records.partition(&:active?)
+
+            if held.empty?
+              say("No locks held.")
+            else
+              say("Locks held (#{held.size}):")
+              report_records(held, json: false, stale_minutes: stale_minutes)
+            end
+
+            report_interrupted(interrupted, stale_minutes) if interrupted.any?
+          end
+
+          # Each orphan is followed by its two ways out, on STDERR, so what
+          # goes down a pipe is the listing alone.
+          #
+          # @param records [Array<Record>] orphaned locks
+          # @param stale_minutes [Integer]
+          def report_interrupted(records, stale_minutes)
+            say("Interrupted (#{records.size}):")
+            records.each do |record|
+              report_records([record], json: false, stale_minutes: stale_minutes)
+              advise_interrupted(record)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/mine.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # What this session holds, and what its sub-agents hold, since those
+        # are what its `release-all` would take with it. Never its parent's:
+        # a sub-agent that saw those as its own could release them.
+        class Mine < Base
+          desc "Locks held by this session and its sub-agents"
+
+          option :json, type: :boolean, default: false, desc: "Machine-readable output"
+
+          # @param options [Hash]
+          # @return [Manager::Result]
+          def call(**options)
+            manager = manager(options[:dir])
+            result = manager.mine
+
+            if result.records.empty?
+              say(options[:json] ? "[]" : "No locks held by #{manager.identity.id}.")
+            else
+              report_records(result.records, json: options[:json], stale_minutes: manager.stale_minutes)
+            end
+
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/note.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Write down where you are, in the lock itself.
+        #
+        # The lock and the notes have one lifespan on purpose. A machine that
+        # reboots loses the session but not the file, so the next run reads one
+        # document and knows what was underway and how far it got.
+        class Note < Base
+          desc "Record progress inside a lock you hold"
+
+          argument :scope, required: true, desc: "The path or glob you locked"
+          argument :text, required: true, desc: "What just happened"
+
+          example ["workflow/** 'installer rewritten, specs still red'"]
+
+          def call(scope:, text:, **options)
+            result = manager(options[:dir]).note(scope, text)
+
+            case result.status
+            when :noted then say("NOTED #{result.record.scope}")
+            when :not_found then warn_("NOT LOCKED #{scope}, take the lock before writing in it")
+            when :refused then warn_("REFUSED: #{result.record.scope} is held by #{result.record.agent_id}")
+            end
+
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/release.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Give a scope back.
+        class Release < Base
+          desc "Release a lock you hold"
+
+          argument :scope, required: true, desc: "The path or glob you locked"
+
+          example ["workflow/**", "lib/agent/lock/cli.rb"]
+
+          def call(scope:, **options)
+            result = manager(options[:dir]).release(scope)
+
+            case result.status
+            when :released then say("RELEASED #{result.record.scope}")
+            when :not_found then say("NOT LOCKED #{scope}")
+            when :refused
+              warn_("REFUSED: #{result.record.scope} is held by #{result.record.agent_id}, not you")
+            end
+
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end