codex-notify 1.0.0

data/lib/codex_notify/durable_slack_publisher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'message_formatter'
+require_relative 'slack_delivery_worker'
+
+module CodexNotify
+  class DurableSlackPublisher
+    def initialize(client:, store:, outbox:, channel:, throttle_sec: 0.0)
+      @store = store
+      @outbox = outbox
+      @channel = channel
+      @worker = SlackDeliveryWorker.new(outbox:, client:, store:, inter_message_delay: throttle_sec)
+      @queued_ids = []
+    end
+
+    attr_reader :queued_ids
+
+    def publish_standalone(key:, message:)
+      enqueue(key:, action: :standalone, message:)
+    end
+
+    def ensure_thread(key:, root_message:)
+      return if @store.thread_ts_for(key)
+      return if @outbox.pending_root?(key, generation: @store.generation_for(key))
+
+      enqueue(key:, action: :ensure_thread, message: root_message)
+    end
+
+    def publish_root_or_reply(key:, message:)
+      enqueue(key:, action: :root_or_reply, message:, recovery_root_message: message)
+    end
+
+    def publish_reply(key:, message:, recovery_root_message:)
+      has_root = @store.thread_ts_for(key) || @outbox.pending_root?(key, generation: @store.generation_for(key))
+      return unless has_root
+
+      enqueue(key:, action: :reply, message:, recovery_root_message: recovery_root_message || message)
+    end
+
+    def reset(key:)
+      @store.advance_generation(key)
+    end
+
+    def drain
+      @worker.drain(channel: @channel)
+    end
+
+    def key(namespace, identity)
+      Digest::SHA256.hexdigest("#{namespace}\0#{identity}")
+    end
+
+    private
+
+    def enqueue(key:, action:, message:, recovery_root_message: nil)
+      chunks = message ? MessageFormatter.chunks(message).to_a : []
+      recovery_chunks = recovery_root_message ? MessageFormatter.chunks(recovery_root_message).to_a : []
+      id = @outbox.enqueue(
+        channel: @channel,
+        ordering_key: key,
+        generation: @store.generation_for(key),
+        action:,
+        chunks:,
+        recovery_chunks:
+      )
+      @queued_ids << id
+      id
+    end
+  end
+end

data/lib/codex_notify/env_source_loader.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'config_support'
+require_relative 'trusted_config_loader'
+
+module CodexNotify
+  class EnvSourceLoader
+    class Error < StandardError; end
+
+    Source = Struct.new(:kind, :path, :values, keyword_init: true)
+    LookupResult = Struct.new(:value, :source, keyword_init: true)
+
+    class SourceSet
+      include Enumerable
+
+      def initialize(sources)
+        @sources = sources.freeze
+      end
+
+      def each(&block)
+        @sources.each(&block)
+      end
+
+      def lookup(key)
+        each do |source|
+          value = source.values[key]
+          return LookupResult.new(value:, source:) if value && !value.empty?
+        end
+        nil
+      end
+
+      def excluding_kind(kind)
+        self.class.new(reject { |source| source.kind == kind })
+      end
+
+      def restrict_kind(kind, keys:)
+        self.class.new(map do |source|
+          next source unless source.kind == kind
+
+          Source.new(kind: source.kind, path: source.path, values: source.values.slice(*keys))
+        end)
+      end
+    end
+
+    include ConfigSupport
+    private(*ConfigSupport.instance_methods(false))
+
+    def initialize(legacy_checkout_root: nil, environment: ENV, stderr: $stderr, config_loader: nil)
+      @legacy_checkout_root = Pathname(legacy_checkout_root).expand_path if legacy_checkout_root
+      @environment = environment
+      @stderr = stderr
+      @config_loader = config_loader || TrustedConfigLoader.new(environment:, stderr:)
+    end
+
+    def load(path: ConfigSupport::DEFAULT_ENV_PATH, explicit: false, config_path: nil)
+      process = Source.new(kind: :process, path: nil, values: @environment.to_h)
+      files = resolve_env_paths(path, legacy_checkout_root:).map { |env_path| load_file(env_path, explicit:) }
+      configs = @config_loader.load(explicit_path: config_path).map do |config|
+        Source.new(kind: config.kind, path: config.path, values: config.values)
+      end
+      explicit_config, default_config = configs.partition { |source| source.kind == :config_explicit }
+
+      ordered = if explicit
+                  [process, *explicit_config, *files, *default_config]
+                else
+                  [process, *explicit_config, *default_config, *files]
+                end
+      SourceSet.new(ordered)
+    end
+
+    private
+
+    attr_reader :legacy_checkout_root
+
+    def load_file(path, explicit:)
+      ConfigDiagnostics.warn_if_env_file_insecure(path, stderr: @stderr)
+      Source.new(kind: source_kind(path, explicit:), path: path.expand_path, values: Dotenv.parse(path.to_s))
+    rescue SystemCallError => e
+      raise Error, "could not read env file #{path}: #{e.class}"
+    end
+
+    def source_kind(path, explicit:)
+      return :explicit if explicit
+
+      return :repository unless legacy_checkout_root
+
+      checkout_env_path = legacy_checkout_root.join(ConfigSupport::DEFAULT_ENV_PATH)
+      File.identical?(path, checkout_env_path) ? :tool : :repository
+    end
+  end
+end

data/lib/codex_notify/hook_cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'hook_config'
+require_relative 'hook_input_validator'
+require_relative 'hook_runner'
+require_relative 'message_formatter'
+require_relative 'outbox_commands'
+
+module CodexNotify
+  module HookCLI
+    MAX_STDIN_BYTES = 1_048_576
+
+    module_function
+
+    def main(argv = nil, stdin: $stdin, stderr: $stderr, stdout: $stdout,
+             runner_factory: HookRunner.method(:new), legacy_checkout_root: nil)
+      args = HookConfig.parse_args(argv, stderr:, legacy_checkout_root:)
+
+      if args.migrate_config
+        env_path = args.env_file if args.env_file_explicit
+        return ConfigMigrator.new(legacy_checkout_root:, stdout:, stderr:).run(
+          env_path:,
+          config_path: args.config_file
+        )
+      end
+
+      if args.outbox_action
+        return OutboxCommands.run(
+          action: args.outbox_action,
+          id: args.outbox_id,
+          outbox_dir: args.outbox_dir,
+          token: args.token,
+          channel: args.channel,
+          state_file: args.state_file,
+          stdout:,
+          stderr:
+        )
+      end
+
+      unless args.token && args.channel
+        stderr.puts('ERROR: need --token/--channel or a Slack destination from environment or config file')
+        return 2
+      end
+
+      payload = parse_stdin(stdin)
+      event = HookInputValidator.validate(event_name: args.event_name, payload:)
+
+      runner = runner_factory.call(
+        token: args.token,
+        channel: args.channel,
+        user_name: args.user_name,
+        title: args.title,
+        state_file: args.state_file,
+        outbox_dir: args.outbox_dir,
+        mode: args.mode,
+        stdout: stdout
+      )
+      code = runner.run(event:)
+      stderr.puts('ERROR: Slack delivery requires outbox review; run --outbox-status') if code == 1
+      code
+    rescue Interrupt
+      0
+    rescue HookInputError => e
+      stderr.puts("ERROR: #{e.message}")
+      2
+    rescue HookConfig::Error, ConfigMigrator::Error, OptionParser::ParseError => e
+      stderr.puts("ERROR: #{e.message}")
+      2
+    rescue StandardError => e
+      stderr.puts("ERROR: #{e.class}: #{e.message}")
+      1
+    end
+
+    def parse_stdin(stdin)
+      raw = stdin.read(MAX_STDIN_BYTES + 1).to_s
+      if raw.bytesize > MAX_STDIN_BYTES
+        raise HookInputError, "hook stdin exceeds maximum size of #{MAX_STDIN_BYTES} bytes"
+      end
+      raise HookInputError, 'hook stdin is empty' if raw.strip.empty?
+
+      payload = JSON.parse(raw)
+      raise HookInputError, 'hook payload must be a JSON object' unless payload.is_a?(Hash)
+
+      payload
+    rescue JSON::ParserError
+      raise HookInputError, 'hook stdin is not valid JSON'
+    end
+  end
+end

data/lib/codex_notify/hook_config.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'pathname'
+require_relative 'config_support'
+require_relative 'config_migrator'
+require_relative 'destination_resolver'
+require_relative 'env_source_loader'
+
+module CodexNotify
+  module HookConfig
+    extend ConfigSupport
+
+    DEFAULT_ENV_PATH = ConfigSupport::DEFAULT_ENV_PATH
+    DEFAULT_STATE_PATH = Pathname(File.expand_path('~/.codex-notify-hook/state.json'))
+    DEFAULT_MODE = 'normal'
+    MODES = %w[normal debug].freeze
+    class Error < StandardError; end
+
+    Args = Struct.new(
+      :env_file,
+      :env_file_explicit,
+      :config_file,
+      :migrate_config,
+      :token,
+      :channel,
+      :destination,
+      :user_name,
+      :title,
+      :state_file,
+      :event_name,
+      :mode,
+      :outbox_dir,
+      :outbox_action,
+      :outbox_id,
+      :token_from_cli,
+      keyword_init: true
+    )
+
+    module_function
+
+    def build_parser
+      options = Args.new(
+        env_file: DEFAULT_ENV_PATH,
+        env_file_explicit: false,
+        config_file: nil,
+        migrate_config: false,
+        token: nil,
+        channel: nil,
+        destination: nil,
+        user_name: nil,
+        title: nil,
+        state_file: DEFAULT_STATE_PATH.to_s,
+        event_name: nil,
+        mode: nil,
+        outbox_dir: nil,
+        outbox_action: nil,
+        outbox_id: nil,
+        token_from_cli: false
+      )
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: codex-notify-hook [options]'
+        add_common_options(opts, options)
+        opts.on('--state-file PATH') { |v| options.state_file = v }
+        opts.on('--event NAME') { |v| options.event_name = v }
+        opts.on('--mode MODE', MODES) { |v| options.mode = v }
+        opts.on('--outbox-dir PATH') { |v| options.outbox_dir = v }
+      end
+
+      [parser, options]
+    end
+
+    def parse_args(argv = nil, stderr: $stderr, legacy_checkout_root: nil)
+      parser, options = build_parser
+      parser.parse!(argv || [])
+      return options if options.migrate_config
+
+      ConfigDiagnostics.warn_deprecated_cli_token(stderr:) if options.token_from_cli
+
+      sources = EnvSourceLoader.new(legacy_checkout_root:, stderr:).load(
+        path: options.env_file,
+        explicit: options.env_file_explicit,
+        config_path: options.config_file
+      )
+      policy = resolve_policy(sources, stderr:)
+      warn_ignored_repository_values(sources, policy:, stderr:)
+      apply_destination(options, sources, policy:, stderr:)
+      apply_presentation(options, sources, policy:)
+      options.outbox_dir ||= "#{options.state_file}.outbox"
+
+      raise Error, "mode must be one of: #{MODES.join(', ')}" unless MODES.include?(options.mode)
+      options
+    rescue ConfigSupport::Error, EnvSourceLoader::Error, TrustedConfigLoader::Error, DestinationResolver::Error => e
+      raise Error, e.message
+    end
+
+    def apply_presentation(options, sources, policy:)
+      eligible = eligible_sources(sources, policy:)
+      trusted = trusted_sources(sources)
+      options.user_name ||= eligible.lookup('CODEX_NOTIFY_USER_NAME')&.value || system_user_name
+      options.title ||= eligible.lookup('CODEX_NOTIFY_TITLE')&.value
+      options.event_name ||= eligible.lookup('CODEX_HOOK_EVENT')&.value ||
+                            eligible.lookup('CODEX_NOTIFY_HOOK_EVENT')&.value
+      options.mode ||= eligible.lookup('CODEX_NOTIFY_MODE')&.value || DEFAULT_MODE
+      options.outbox_dir ||= trusted.lookup('CODEX_NOTIFY_OUTBOX_DIR')&.value
+    end
+
+  end
+end

data/lib/codex_notify/hook_event.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CodexNotify
+  HookEvent = Data.define(
+    :name,
+    :session_id,
+    :cwd,
+    :source,
+    :prompt,
+    :tool_name,
+    :tool_input,
+    :tool_response,
+    :assistant_message,
+    :raw_payload
+  )
+end

data/lib/codex_notify/hook_formatter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'message_formatter'
+
+module CodexNotify
+  module HookFormatter
+    module_function
+
+    def session_root_message(event, title:, user_name:)
+      body = [
+        'Codex hook notification started.',
+        "CWD: #{event.cwd}",
+        "User: #{user_name}",
+        "Session ID: #{event.session_id}"
+      ].join("\n")
+      tool_message(title, body)
+    end
+
+    def prompt_message(event, user_name:)
+      MessageFormatter.message(title: user_name, body: event.prompt, presentation: :plain)
+    end
+
+    def assistant_message(event)
+      MessageFormatter.message(title: 'assistant', body: event.assistant_message, presentation: :plain)
+    end
+
+    def tool_message(title, body)
+      MessageFormatter.message(title:, body:, presentation: :block)
+    end
+
+    def pre_tool_message(event)
+      command = event.tool_input['command']
+      if command.nil? || command.to_s.empty?
+        payload = JSON.pretty_generate(event.raw_payload)
+        return tool_message('tool', payload)
+      end
+
+      tool_message('tool', "$ #{command}")
+    end
+
+    def post_tool_message(event)
+      output = event.tool_response['output']
+      exit_code = event.tool_response['exit_code']
+      stderr = event.tool_response['stderr']
+
+      parts = []
+      parts << "[exit_code] #{exit_code}" unless exit_code.nil?
+      parts << "[output]\n#{output}" unless output.nil? || output.to_s.empty?
+      parts << "[stderr]\n#{stderr}" unless stderr.nil? || stderr.to_s.empty?
+      parts = [JSON.pretty_generate(event.raw_payload)] if parts.empty?
+      tool_message('tool', parts.join("\n\n"))
+    end
+
+    def permission_request_message(event)
+      description = event.tool_input['description']
+      description ||= 'Codex is waiting for your approval.'
+      tool_message("approval required: #{event.tool_name}", description)
+    end
+  end
+end

data/lib/codex_notify/hook_input_validator.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require_relative 'hook_event'
+
+module CodexNotify
+  class HookInputError < StandardError; end
+
+  module HookInputValidator
+    EVENT_ALIASES = {
+      'userpromptsubmit' => 'UserPromptSubmit',
+      'pretooluse' => 'PreToolUse',
+      'posttooluse' => 'PostToolUse',
+      'permissionrequest' => 'PermissionRequest',
+      'stop' => 'Stop',
+      'sessionstart' => 'SessionStart'
+    }.freeze
+    SUPPORTED_EVENTS = EVENT_ALIASES.values.freeze
+
+    module_function
+
+    def validate(event_name:, payload:)
+      raise HookInputError, 'hook payload must be a JSON object' unless payload.is_a?(Hash)
+
+      normalized_event = validate_event_name(event_name, payload)
+      session_id = validate_session_id(payload)
+      attributes = normalize_event_payload(normalized_event, payload)
+      HookEvent.new(
+        name: immutable_copy(normalized_event),
+        session_id: immutable_copy(session_id),
+        cwd: immutable_copy(payload['cwd'] || Dir.pwd),
+        source: nil,
+        prompt: nil,
+        tool_name: nil,
+        tool_input: nil,
+        tool_response: nil,
+        assistant_message: nil,
+        raw_payload: nil,
+        **attributes
+      )
+    end
+
+    def normalize_event_name(name)
+      return nil unless name.is_a?(String)
+
+      text = name.strip
+      return nil if text.empty?
+      return text if SUPPORTED_EVENTS.include?(text)
+
+      EVENT_ALIASES[text.downcase.gsub(/[_\s-]/, '')] || text
+    end
+
+    def validate_event_name(event_name, payload)
+      names = [event_name, payload['hook_event_name'], payload['event']].compact
+      raise HookInputError, 'hook event name is required' if names.empty?
+
+      normalized = names.map do |name|
+        value = normalize_event_name(name)
+        raise HookInputError, 'hook event name must be a non-empty string' if value.nil?
+        raise HookInputError, 'unsupported hook event' unless SUPPORTED_EVENTS.include?(value)
+
+        value
+      end
+      raise HookInputError, 'hook event names from arguments and payload do not match' unless normalized.uniq.one?
+
+      normalized.first
+    end
+    private_class_method :validate_event_name
+
+    def validate_session_id(payload)
+      candidates = [
+        payload['session_id'],
+        payload['sessionId'],
+        nested_session_id(payload)
+      ].compact
+      raise HookInputError, 'hook session ID is required' if candidates.empty?
+
+      normalized = candidates.map do |value|
+        unless value.is_a?(String) && !value.strip.empty?
+          raise HookInputError, 'hook session ID must be a non-empty string'
+        end
+
+        value.strip
+      end
+      raise HookInputError, 'hook session IDs in payload do not match' unless normalized.uniq.one?
+
+      normalized.first
+    end
+    private_class_method :validate_session_id
+
+    def nested_session_id(payload)
+      session = payload['session']
+      return nil if session.nil?
+      raise HookInputError, 'hook session must be an object' unless session.is_a?(Hash)
+
+      session['id']
+    end
+    private_class_method :nested_session_id
+
+    def normalize_event_payload(event_name, payload)
+      case event_name
+      when 'SessionStart'
+        source = payload_value(payload, 'source')
+        require_non_empty_string(source, event_name, 'source')
+        { source: immutable_copy(source) }
+      when 'UserPromptSubmit'
+        prompt = payload_value(payload, 'prompt')
+        require_non_empty_string(prompt, event_name, 'prompt')
+        { prompt: immutable_copy(prompt) }
+      when 'PreToolUse'
+        tool_name = require_tool_name(payload, event_name)
+        tool_input = normalize_pre_tool_input(payload, event_name)
+        raw_payload = payload unless displayable_command?(tool_input['command'])
+        { tool_name:, tool_input:, raw_payload: immutable_copy(raw_payload) }
+      when 'PostToolUse'
+        tool_name = require_tool_name(payload, event_name)
+        tool_response = normalize_post_tool_response(payload, event_name)
+        raw_payload = payload unless displayable_tool_response?(tool_response)
+        { tool_name:, tool_response:, raw_payload: immutable_copy(raw_payload) }
+      when 'PermissionRequest'
+        tool_name = require_tool_name(payload, event_name)
+        value = payload_value(payload, 'tool_input')
+        require_hash(value, event_name, 'tool_input')
+        tool_input = { 'description' => immutable_copy(value['description']) }.freeze
+        { tool_name:, tool_input: }
+      when 'Stop'
+        value, present = payload_value_with_presence(payload, 'last_assistant_message')
+        raise HookInputError, 'Stop requires last_assistant_message' unless present
+        raise HookInputError, 'Stop last_assistant_message must be a string' unless value.is_a?(String)
+
+        { assistant_message: immutable_copy(value) }
+      end
+    end
+    private_class_method :normalize_event_payload
+
+    def require_tool_name(payload, event_name)
+      value = payload_value(payload, 'tool_name')
+      require_non_empty_string(value, event_name, 'tool_name')
+      immutable_copy(value)
+    end
+    private_class_method :require_tool_name
+
+    def normalize_pre_tool_input(payload, event_name)
+      value, present = payload_value_with_presence(payload, 'tool_input')
+      if present
+        valid = value.is_a?(Hash) || (value.is_a?(String) && !value.strip.empty?)
+        raise HookInputError, "#{event_name} tool_input must be an object or non-empty string" unless valid
+
+        command = value.is_a?(Hash) ? value['command'] : value
+        return immutable_copy('command' => command)
+      end
+
+      command, command_present = payload_value_with_presence(payload, 'command')
+      valid_command = (command.is_a?(Array) && !command.empty?) ||
+                      (command.is_a?(String) && !command.strip.empty?)
+      return immutable_copy('command' => command) if command_present && valid_command
+
+      raise HookInputError, "#{event_name} requires tool_input or command"
+    end
+    private_class_method :normalize_pre_tool_input
+
+    def normalize_post_tool_response(payload, event_name)
+      value, present = payload_value_with_presence(payload, 'tool_response')
+      if present && !value.is_a?(Hash) && !value.is_a?(String)
+        raise HookInputError, "#{event_name} tool_response must be an object or string"
+      end
+
+      legacy_fields = %w[tool_output output exit_code stderr]
+      legacy_present = legacy_fields.any? do |field|
+        legacy_value, legacy_present = payload_value_with_presence(payload, field)
+        legacy_present && !legacy_value.nil?
+      end
+      unless present || legacy_present
+        raise HookInputError, "#{event_name} requires tool_response or a supported legacy result field"
+      end
+
+      response = value.is_a?(Hash) ? value : {}
+      output = response['output'] || response['stdout'] || (value unless value.is_a?(Hash))
+      output ||= payload_value(payload, 'tool_output') || payload_value(payload, 'output')
+      exit_code = response['exit_code'] || response['exitCode'] || payload_value(payload, 'exit_code')
+      stderr = response['stderr'] || payload_value(payload, 'stderr')
+
+      immutable_copy('output' => output, 'exit_code' => exit_code, 'stderr' => stderr)
+    end
+    private_class_method :normalize_post_tool_response
+
+    def displayable_command?(command)
+      !command.nil? && !command.to_s.empty?
+    end
+    private_class_method :displayable_command?
+
+    def displayable_tool_response?(response)
+      !response['exit_code'].nil? ||
+        (!response['output'].nil? && !response['output'].to_s.empty?) ||
+        (!response['stderr'].nil? && !response['stderr'].to_s.empty?)
+    end
+    private_class_method :displayable_tool_response?
+
+    def require_non_empty_string(value, event_name, field)
+      return if value.is_a?(String) && !value.strip.empty?
+
+      raise HookInputError, "#{event_name} requires non-empty #{field}"
+    end
+    private_class_method :require_non_empty_string
+
+    def require_hash(value, event_name, field)
+      return if value.is_a?(Hash)
+
+      raise HookInputError, "#{event_name} requires #{field} to be an object"
+    end
+    private_class_method :require_hash
+
+    def payload_value(payload, key)
+      payload_value_with_presence(payload, key).first
+    end
+    private_class_method :payload_value
+
+    def payload_value_with_presence(payload, key)
+      return [payload[key], true] if payload.key?(key)
+
+      nested = payload['payload']
+      return [nested[key], true] if nested.is_a?(Hash) && nested.key?(key)
+
+      [nil, false]
+    end
+    private_class_method :payload_value_with_presence
+
+    def immutable_copy(value)
+      case value
+      when Hash
+        value.to_h { |key, item| [immutable_copy(key), immutable_copy(item)] }.freeze
+      when Array
+        value.map { |item| immutable_copy(item) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+    private_class_method :immutable_copy
+  end
+end