claude-inbox 0.1.0

data/lib/claude_inbox/slash_commands.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "settings"
+
+module ClaudeInbox
+  # The slash commands `claude` would offer at its own prompt, read from the
+  # same places it reads them: `.claude/commands/*.md` and
+  # `.claude/skills/*/SKILL.md` under the project and the home directory,
+  # the skills and commands of installed plugins (named `plugin:name`), and
+  # the skills claude.ai syncs down (`anthropic-skills:name`). Built-ins
+  # live inside the CLI and are not listed; typing one still works, since
+  # the prompt goes to `claude --bg` verbatim.
+  #
+  # Pure: filesystem in, plain values out. Nothing here runs `claude`.
+  module SlashCommands
+    Command = Struct.new(:name, :description, :source) do
+      def to_s = "/#{name}"
+    end
+
+    SYNCED_PLUGIN = "anthropic-skills"
+
+    module_function
+
+    # The project wins over the home directory when both define the same
+    # name, as it does in the CLI.
+    def list(cwd:, home: Dir.home)
+      found = {}
+      add = ->(cmd) { found[cmd.name] ||= cmd }
+      local(File.join(cwd, ".claude"), "project").each(&add)
+      local(File.join(home, ".claude"), "user").each(&add)
+      plugins(home).each(&add)
+      synced(home).each(&add)
+      found.values.sort_by(&:name)
+    end
+
+    def match(commands, query)
+      q = query.downcase
+      starts, rest = commands.partition { |c| c.name.downcase.start_with?(q) }
+      starts + rest.select { |c| c.name.downcase.include?(q) }
+    end
+
+    def local(dir, source)
+      skills(File.join(dir, "skills"), source) + commands(File.join(dir, "commands"), source)
+    end
+
+    def skills(dir, source, prefix: nil)
+      Dir.glob(File.join(dir, "*", "SKILL.md")).sort.filter_map do |path|
+        meta = frontmatter(path)
+        next if meta["user-invocable"] == "false"
+        name = File.basename(File.dirname(path))
+        Command.new(qualify(prefix, name), meta["description"].to_s, source)
+      end
+    end
+
+    # A command file's name is its own; a subdirectory only groups them.
+    def commands(dir, source, prefix: nil)
+      Dir.glob(File.join(dir, "**", "*.md")).sort.map do |path|
+        name = File.basename(path, ".md")
+        Command.new(qualify(prefix, name), frontmatter(path)["description"].to_s, source)
+      end
+    end
+
+    # "name", or "plugin:name" when it comes from a plugin.
+    def qualify(prefix, name) = [prefix, name].compact.join(":")
+
+    # `installed_plugins.json` maps "name@marketplace" to where the plugin
+    # was unpacked: one entry, or a list of them, one per install scope.
+    def plugins(home)
+      installed = Settings.read(File.join(home, ".claude", "plugins", "installed_plugins.json"))
+      (installed["plugins"] || {}).flat_map do |key, entries|
+        plugin = key.split("@").first
+        Array(entries).filter_map { |e| e["installPath"] if e.is_a?(Hash) }.uniq.flat_map do |root|
+          skills(File.join(root, "skills"), "plugin", prefix: plugin) +
+            commands(File.join(root, "commands"), "plugin", prefix: plugin)
+        end
+      end
+    end
+
+    # claude.ai's synced skills sit in one bucket per account under
+    # ~/.claude/skills/synced and answer to the anthropic-skills prefix.
+    def synced(home)
+      Dir.glob(File.join(home, ".claude", "skills", "synced", "*", "")).flat_map do |bucket|
+        skills(bucket, "synced", prefix: SYNCED_PLUGIN)
+      end
+    end
+
+    # The YAML front matter's scalar keys, without a YAML parser: enough
+    # for `name`, `description` and `user-invocable`. A folded or quoted
+    # description is read up to its first line.
+    def frontmatter(path)
+      lines = File.foreach(path).first(60)
+      return {} unless lines.first&.strip == "---"
+      out = {}
+      key = nil
+      lines[1..].map(&:chomp).each do |line|
+        break if line.strip == "---"
+        if (m = line.match(/\A([\w-]+):\s*(.*)\z/))
+          key = m[1]
+          out[key] = unquote(m[2].strip)
+        elsif key && out[key].empty? && line.start_with?(" ")
+          out[key] = unquote(line.strip)
+        end
+      end
+      out
+    rescue Errno::ENOENT, Errno::EACCES
+      {}
+    end
+
+    def unquote(s)
+      s = s.sub(/\A[>|][-+]?\z/, "")
+      quoted = s.size >= 2 && ((s.start_with?('"') && s.end_with?('"')) || (s.start_with?("'") && s.end_with?("'")))
+      s = s[1..-2] if quoted
+      s.gsub("''", "'")
+    end
+  end
+end

data/lib/claude_inbox/store/entry.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  class Store
+    # What the inbox remembers about one session between polls, over the hash
+    # state.json holds; the key names appear nowhere else. Mutators edit that
+    # hash in place, since `Store#edit` yields it from the table and saves.
+    class Entry
+      # For a key edited before any poll has seen it (`s` on a row that only just appeared).
+      def self.blank(now) = new("state_since" => now.to_i)
+
+      # A finished session with no process has been quiet since it finished,
+      # not since this poll, so its idle clock starts from `started_at`.
+      def self.first_seen(session, now)
+        since = (session.finished? && !session.alive? && session.started_at) ? session.started_at.to_i : now.to_i
+        new("last_state" => session.effective_state, "state_since" => since)
+      end
+
+      def self.observe(hash, session, now)
+        (hash ? new(hash) : first_seen(session, now)).observe(session, now)
+      end
+
+      def self.snooze_until(choice, now)
+        case choice
+        when :m15 then now.to_i + 15 * 60
+        when :h1 then now.to_i + 3600
+        when :tomorrow_9am
+          t = Time.at(now.to_i)
+          t9 = Time.new(t.year, t.month, t.day, 9, 0, 0, t.utc_offset)
+          t9 += 86_400 if t9 <= t
+          t9.to_i
+        when :until_woken then UNTIL_WOKEN
+        else raise ArgumentError, "unknown snooze #{choice.inspect}"
+        end
+      end
+
+      def initialize(hash)
+        @h = hash
+      end
+
+      def to_h = @h
+
+      def alias_name = @h["alias"]
+
+      def pr = @h["pr"]
+
+      def wake_at = @h["wake_at"]
+
+      def parked? = wake_at == UNTIL_WOKEN
+
+      def snoozed_at = @h["snoozed_at"]
+
+      def last_state = @h["last_state"]
+
+      def state_since = @h["state_since"]
+
+      def last_seen = @h["last_seen"]
+
+      def pinned? = @h["pinned"] ? true : false
+
+      def pinned_at = @h["pinned_at"]
+
+      def settled_at = @h["settled_at"]
+
+      def acknowledged_at = @h["acknowledged_at"]
+
+      def revived_at = @h["revived_at"]
+
+      # When `claude rm` last refused this session, so the Reaper backs off.
+      def reap_failed_at = @h["reap_failed_at"]
+
+      def reap_error = @h["reap_error"]
+
+      def stale?(now) = last_seen && now.to_i - last_seen > PRUNE_AFTER
+
+      def observe(session, now)
+        now_i = now.to_i
+        if last_state != session.effective_state
+          @h["last_state"] = session.effective_state
+          @h["state_since"] = now_i
+        end
+        @h["last_seen"] = now_i
+        row = Row.new(session: session, entry: self)
+        @h.delete("wake_at") if row.woken?(now_i)
+        @h.delete("snoozed_at") unless wake_at
+        @h.delete("settled_at") if settled_at && !row.hand_settled?
+        @h.delete("acknowledged_at") if acknowledged_at && !row.acknowledged?
+        @h.delete("revived_at") if revived_at && !row.revived?
+        self
+      end
+
+      def snooze(choice, now)
+        @h["wake_at"] = self.class.snooze_until(choice, now)
+        @h["snoozed_at"] = now.to_i
+      end
+
+      # Also lifts a hand-settle and a PR settle, so `u` undoes `x` and a resolved PR alike.
+      def wake(now)
+        @h.delete("wake_at")
+        @h.delete("snoozed_at")
+        @h.delete("settled_at")
+        @h["revived_at"] = now.to_i
+      end
+
+      # Also lifts a prior revive: otherwise revived_at would still outrank
+      # the fresh settle in `Row#section` and `x` after `u` would do nothing.
+      def settle(now)
+        @h["settled_at"] = now.to_i
+        @h.delete("wake_at")
+        @h.delete("snoozed_at")
+        @h.delete("revived_at")
+      end
+
+      def acknowledge(now)
+        @h["acknowledged_at"] = now.to_i
+      end
+
+      def toggle_pin(now)
+        if @h["pinned"]
+          @h.delete("pinned")
+          @h.delete("pinned_at")
+        else
+          @h["pinned"] = true
+          @h["pinned_at"] = now.to_i
+        end
+      end
+
+      def alias=(name)
+        name.to_s.empty? ? @h.delete("alias") : @h["alias"] = name
+      end
+
+      def pr=(url)
+        url.to_s.empty? ? @h.delete("pr") : @h["pr"] = url
+      end
+
+      # So the Reaper backs off instead of shelling out every poll at a
+      # worktree that is never going to let go of its unpushed commits.
+      def mark_reap_failed(now, message)
+        @h["reap_failed_at"] = now.to_i
+        @h["reap_error"] = message.to_s.lines.first&.strip
+      end
+    end
+  end
+end

data/lib/claude_inbox/store/row.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  class Store
+    # A session paired with its Entry (nil until a poll has recorded one), with
+    # the triage rules as its methods; each takes `now`, so a Row is pure.
+    Row = Struct.new(:session, :entry) do
+      def id = session.id
+
+      def key = session.key
+
+      def selectable? = !key.nil?
+
+      def alias_name = entry&.alias_name
+
+      def label = alias_name || session.display_name
+
+      def wake_at = entry&.wake_at
+
+      def parked? = entry&.parked?
+
+      def state_since = entry&.state_since
+
+      def pinned_at = entry&.pinned_at
+
+      def pinned? = entry&.pinned?
+
+      def reap_failed_at = entry&.reap_failed_at
+
+      def matches?(query)
+        q = query.downcase
+        label.downcase.include?(q) || session.cwd.to_s.downcase.include?(q)
+      end
+
+      # A session already blocked when you snoozed it stays snoozed; one that
+      # *becomes* blocked or fails afterwards wakes early.
+      def woken?(now)
+        return false if wake_at.nil?
+        return true if session.needs_you? && entry.state_since.to_i > entry.snoozed_at.to_i
+        return false if parked?
+        wake_at.to_i <= now.to_i
+      end
+
+      def snoozed?(now) = wake_at && !woken?(now)
+
+      # `x` holds through the session finishing; any other state change afterwards lifts it.
+      def hand_settled?
+        return false unless entry&.settled_at
+        session.finished? || entry.state_since.to_i <= entry.settled_at.to_i
+      end
+
+      # Attaching marks the current state seen: out of Needs You, but into
+      # Active rather than Settled, until the state changes again.
+      def acknowledged?
+        entry&.acknowledged_at && entry.state_since.to_i <= entry.acknowledged_at.to_i
+      end
+
+      # `u` overrides hand-settle and the PR rule alike, and holds until the
+      # state actually changes rather than just for the next poll.
+      def revived?
+        entry&.revived_at && entry.state_since.to_i <= entry.revived_at.to_i
+      end
+
+      # Resolved PRs settle a `blocked` row too: asking "anything need
+      # changing?" leaves it blocked, and merging answers it. `failed` stays
+      # in view even if its PR landed; a PR nobody knows the state of yet
+      # (no gh, offline) is ignored.
+      def settled?
+        return true if hand_settled?
+        return false if UNSETTLEABLE.include?(session.effective_state)
+        known = session.prs.select(&:known?)
+        known.any? && known.all?(&:resolved?)
+      end
+
+      # Idle time is the only clock, not the Settled section: the PR rule holds
+      # an abandoned draft in Active for ever, so the deadest rows are the ones
+      # Settled never reaches. A session with no entry waits a poll, so its
+      # idle time is seeded from `started_at` rather than guessed.
+      def reapable?(now)
+        return false unless session.actionable?
+        return false if session.alive?
+        return false if UNREAPABLE.include?(session.effective_state)
+        return false if entry.nil? || pinned? || snoozed?(now)
+        !state_since.nil? && now.to_i - state_since.to_i > REAP_AFTER
+      end
+
+      # The terminal outranks everything: never settle or hide a session you are in.
+      def section(now)
+        if session.terminal? then session.needs_you? ? :needs_you : :active
+        elsif pinned? then :pinned
+        elsif snoozed?(now) then :snoozed
+        elsif !revived? && hand_settled? then :settled
+        elsif !revived? && settled? then :settled # a resolved PR outranks Needs You
+        elsif session.needs_you? then acknowledged? ? :active : :needs_you
+        elsif session.finished? then :active
+        else :active
+        end
+      end
+    end
+  end
+end

data/lib/claude_inbox/store/sections.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  class Store
+    # The Rows of one poll, grouped and ordered, and where the cursor may land among them.
+    Sections = Struct.new(:pinned, :needs_you, :active, :snoozed, :settled) do
+      def each_section = SECTIONS.each { |k| yield k, self[k] }
+
+      def all = SECTIONS.flat_map { |k| self[k] }
+
+      def row(selection)
+        all.find { |r| r.key == selection.key } if selection&.row?
+      end
+
+      def matching(query)
+        return self if query.nil? || query.empty?
+        self.class.new(**to_h.transform_values { |rows| rows.select { |r| r.matches?(query) } })
+      end
+
+      def section_of(selection)
+        return nil if selection.nil?
+        return selection.key if selection.fold?
+        each_section { |name, rows| return name if rows.any? { |r| r.key == selection.key } }
+        nil
+      end
+
+      def selections(expanded) = stops(expanded).flat_map(&:last)
+
+      # `[name, selection]` per section: its first row, or the fold standing in for them.
+      def heads(expanded)
+        stops(expanded).filter_map { |name, stops| [name, stops.first] if stops.any? }
+      end
+
+      private
+
+      # An empty fold is left out, since there is nothing under it to open.
+      def stops(expanded)
+        SECTIONS.filter_map do |name|
+          rows = self[name]
+          if !Store.folded?(name, expanded) then [name, rows.select(&:selectable?).map { |r| Selection.row(r.key) }]
+          elsif rows.any? then [name, [Selection.fold(name)]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/claude_inbox/store/selection.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  class Store
+    # What the cursor is on: a row, by its key, or a fold, by its section name.
+    Selection = Data.define(:kind, :key) do
+      def self.row(key) = new(kind: :row, key: key)
+
+      def self.fold(section) = new(kind: :fold, key: section)
+
+      def row? = kind == :row
+
+      def fold? = kind == :fold
+    end
+  end
+end

data/lib/claude_inbox/store.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "records"
+require_relative "store/entry"
+require_relative "store/row"
+require_relative "store/selection"
+require_relative "store/sections"
+
+module ClaudeInbox
+  # The last poll and the per-session entry table, behind a mutex, with
+  # state.json underneath.
+  class Store
+    PRUNE_AFTER = 7 * 24 * 3600 # forget entries not seen in a poll for this long
+    REAP_AFTER = 14 * 24 * 3600 # seconds idle before a session is deleted outright
+    UNTIL_WOKEN = "until_woken"
+    # States that hold a row open no matter what its pull requests did.
+    UNSETTLEABLE = %w[working failed].freeze
+    # States never reaped, however long they have been quiet. Shorter than
+    # UNSETTLEABLE on purpose: `failed` earns a permanent row because you
+    # should see it, but after REAP_AFTER of not seeing it, you never will.
+    UNREAPABLE = %w[working].freeze
+    SECTIONS = %i[pinned needs_you active snoozed settled].freeze
+    # Sections long enough to be worth hiding behind a fold toggle.
+    FOLDABLE_SECTIONS = %i[snoozed settled].freeze
+
+    # App and Renderer must agree on this, or j/k lands on rows the frame never painted.
+    def self.folded?(name, expanded) = FOLDABLE_SECTIONS.include?(name) && !expanded[name]
+
+    def self.merge_entries(entries, sessions, now)
+      out = entries.reject { |_, e| Entry.new(e).stale?(now) }.transform_values(&:dup)
+      sessions.each do |s|
+        next unless s.key
+        out[s.key] = Entry.observe(out[s.key], s, now).to_h
+      end
+      out
+    end
+
+    def self.sectionize(sessions, entries, now)
+      sec = Sections.new(pinned: [], needs_you: [], active: [], snoozed: [], settled: [])
+      sessions.each do |s|
+        row = Row.new(session: s, entry: s.key && entries[s.key] && Entry.new(entries[s.key]))
+        sec[row.section(now)] << row
+      end
+      sec.pinned.sort_by! { |r| -(r.pinned_at || 0) }
+      sec.needs_you.sort_by! { |r| -(r.state_since || 0) }
+      sec.active.sort_by! { |r| [r.session.finished? ? 1 : 0, -(r.session.started_at&.to_i || 0)] }
+      sec.snoozed.sort_by! { |r| r.parked? ? [1, 0] : [0, r.wake_at.to_i] }
+      sec.settled.sort_by! { |r| -(r.state_since || 0) }
+      sec
+    end
+
+    DEFAULT_PATH = File.join(Dir.home, ".config", "claude-inbox", "state.json")
+
+    attr_reader :path
+
+    def initialize(path: DEFAULT_PATH, clock: -> { Time.now })
+      @path = path
+      @clock = clock
+      @mutex = Mutex.new
+      @sessions = []
+      @hidden = Set.new
+      @forgotten = Set.new
+      @entries = load
+    end
+
+    # A hidden or forgotten key the daemon has stopped listing is released;
+    # one it still lists stays out of sight.
+    def update(sessions)
+      @mutex.synchronize do
+        keys = sessions.map(&:key)
+        @hidden &= keys
+        @forgotten &= keys
+        @sessions = sessions.reject { |s| @hidden.include?(s.key) || @forgotten.include?(s.key) }
+        @entries = self.class.merge_entries(@entries, @sessions, @clock.call)
+        save
+      end
+    end
+
+    def sections(now = @clock.call)
+      @mutex.synchronize { self.class.sectionize(@sessions, @entries, now) }
+    end
+
+    def sessions = @mutex.synchronize { @sessions.dup }
+
+    def snooze(id, choice) = edit(id) { |e| e.snooze(choice, @clock.call) }
+
+    def wake(id) = edit(id) { |e| e.wake(@clock.call) }
+
+    def acknowledge(id) = edit(id) { |e| e.acknowledge(@clock.call) }
+
+    def settle(id) = edit(id) { |e| e.settle(@clock.call) }
+
+    def mark_reap_failed(id, message) = edit(id) { |e| e.mark_reap_failed(@clock.call, message) }
+
+    def toggle_pin(id) = edit(id) { |e| e.toggle_pin(@clock.call) }
+
+    def set_alias(id, name) = edit(id) { |e| e.alias = name }
+
+    # The local alias, if one is set; nil means the session's own name shows.
+    def alias_for(id) = @mutex.synchronize { @entries[id] && Entry.new(@entries[id]).alias_name }
+
+    def set_pr(id, url) = edit(id) { |e| e.pr = url }
+
+    # The hand-set link, if any; nil means the scanned links are in force.
+    def pr_for(id) = @mutex.synchronize { @entries[id] && Entry.new(@entries[id]).pr }
+
+    def pr_overrides
+      @mutex.synchronize { @entries.transform_values { |e| Entry.new(e).pr }.select { |_, url| url } }
+    end
+
+    def row(session) = Row.new(session: session, entry: session.key && entry(session.key)&.then { |e| Entry.new(e) })
+
+    # The raw hash, for the specs; nothing in lib/ reads it.
+    def entry(id) = @mutex.synchronize { @entries[id]&.dup }
+
+    # Keeps rows out of sight while `claude rm` is on them, so none paints
+    # mid-delete; `release` brings back one `rm` refused. Memory only.
+    def hide(keys)
+      @mutex.synchronize do
+        @hidden.merge(keys)
+        @sessions = @sessions.reject { |s| keys.include?(s.key) }
+      end
+    end
+
+    def release(keys) = @mutex.synchronize { @hidden.subtract(keys) }
+
+    # A session `claude rm` has taken stays hidden until `update` sees the
+    # daemon has dropped it too. Kept apart from `hide` so a `release` on the
+    # same poll cannot bring back what the user deleted.
+    def forget(id)
+      @mutex.synchronize do
+        @forgotten << id
+        @sessions = @sessions.reject { |s| s.key == id }
+        save if @entries.delete(id)
+      end
+    end
+
+    private
+
+    def edit(id)
+      @mutex.synchronize do
+        yield Entry.new(@entries[id] ||= Entry.blank(@clock.call).to_h)
+        save
+      end
+    end
+
+    def load
+      Records.read(@path)["sessions"] || {}
+    end
+
+    def save
+      return unless @path
+      Records.save(@path, {"version" => 1, "sessions" => @entries})
+    end
+  end
+end

data/lib/claude_inbox/subprocess.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ClaudeInbox
+  # Runs a helper command with stdout/stderr captured, in its own session so
+  # it is not associated with our tty. Terminal.app (and others) put the
+  # "active process" of the tty in the tab title; without this the title
+  # flips to "claude" or "ps" on every poll.
+  module Subprocess
+    Result = Struct.new(:out, :err, :status) do
+      def success? = status.success?
+    end
+
+    module_function
+
+    def capture(*argv, chdir: nil)
+      out_r, out_w = IO.pipe
+      err_r, err_w = IO.pipe
+      pid = fork do
+        Process.setsid
+        $stdin.reopen(File::NULL)
+        $stdout.reopen(out_w)
+        $stderr.reopen(err_w)
+        out_r.close
+        err_r.close
+        Dir.chdir(chdir) if chdir
+        exec(*argv)
+      rescue SystemCallError => e
+        $stderr.write(e.message)
+        exit! 127
+      end
+      out_w.close
+      err_w.close
+      out = +""
+      err = +""
+      readers = [out_r, err_r]
+      until readers.empty?
+        ready, = IO.select(readers)
+        ready.each do |io|
+          chunk = io.read_nonblock(65_536, exception: false)
+          if chunk.nil? || chunk == :wait_readable
+            next unless chunk.nil?
+            readers.delete(io)
+            io.close
+          else
+            (io.equal?(out_r) ? out : err) << chunk
+          end
+        end
+      end
+      _, status = Process.wait2(pid)
+      Result.new(out, err, status)
+    end
+  end
+end