antigravity-sdk 0.3.0 → 0.5.0

data/lib/antigravity/policy.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative 'policy/constants'
+
+module Antigravity
+  # ==========================================================================
+  # Antigravity::Policy — Declarative tool-access control for agents.
+  #
+  # ⚠️  ORDER DOES NOT MATTER!
+  #
+  # The DSL is declarative, like SQL — not imperative like a script.
+  # Rules are evaluated by PRECEDENCE, not by insertion order.
+  # You can write `allow` before `deny` or vice versa — same result.
+  #
+  # Precedence (highest wins):
+  #   1. Tool specificity:    specific tool > wildcard (nil)
+  #   2. Condition specificity: has `when:` > no `when:`
+  #   3. Restrictiveness:      deny > confirm > allow
+  #
+  # Example — these two policies behave identically:
+  #
+  #   Policy.define do          Policy.define do
+  #     allow :run_command        deny :run_command, when: cmd('rm')
+  #     deny :run_command,        allow :run_command
+  #       when: cmd('rm')       end
+  #   end
+  #
+  # In both cases, `rm` is denied (conditional deny beats unconditional
+  # allow), and everything else is allowed.
+  #
+  # See policy/constants.rb for curated command/file/tool lists.
+  # ==========================================================================
+  class Policy
+
+    # ------------------------------------------------------------------
+    # Rule — a single allow/deny/confirm entry in a policy.
+    # ------------------------------------------------------------------
+    class Rule
+      attr_reader :action, :tool_name, :condition, :handler
+
+      def initialize(action, tool_name = nil, condition: nil, handler: nil)
+        @action = action
+        @tool_name = tool_name
+        @condition = condition
+        @handler = handler
+      end
+
+      def matches?(tool, args)
+        return false if @tool_name && @tool_name.to_sym != tool.to_sym
+        return false if @condition && !@condition.call(name: tool, args: args)
+        true
+      end
+
+      # Precedence order (higher = wins):
+      # 1. Tool specificity: Specific tool > Wildcard (nil)
+      # 2. Condition specificity: Has predicate > No predicate
+      # 3. Action restrictiveness: Deny > Confirm > Allow
+      def precedence
+        specificity = @tool_name ? 1 : 0
+        condition_score = @condition ? 1 : 0
+        action_score = case @action
+                       when :deny then 3
+                       when :confirm then 2
+                       when :allow then 1
+                       else 0
+                       end
+        [specificity, condition_score, action_score]
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Constructor & factory methods
+    # ------------------------------------------------------------------
+
+    def initialize(&block)
+      @rules = []
+      @confirm_handler = nil
+      instance_eval(&block) if block_given?
+    end
+
+    def self.define(&block)
+      new(&block)
+    end
+
+    def self.allow_all
+      new { allow_all }
+    end
+
+    def self.deny_all
+      new { deny_all }
+    end
+
+    # ------------------------------------------------------------------
+    # Built-in presets
+    # ------------------------------------------------------------------
+
+    # Resolve a preset by name (symbol).
+    # @param name [Symbol] :cautious, :default, :turbo, :test, or :auto
+    # @return [Policy]
+    def self.preset(name)
+      case name.to_sym
+      when :cautious then cautious
+      when :default  then default
+      when :turbo    then turbo
+      when :test     then test
+      when :auto     then auto
+      else
+        raise ArgumentError, "Unknown preset :#{name}. Choose from: #{PRESET_NAMES.map { |n| ":#{n}" }.join(', ')}"
+      end
+    end
+
+    # 🔒 Cautious — read-only free, confirm everything else, hard-deny destructive.
+    # Best for: untrusted environments, production agents.
+    # NOTE: cat/head/tail/ls NOT in safe list — they can bypass view_file deny rules.
+    def self.cautious
+      define do
+        deny_all
+        READONLY_TOOLS.each { |t| allow t }
+        allow :run_command, when: cmd(*SAFE_CMDS, *SAFE_GIT_CMDS)
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        deny :run_command, when: cmd(*RISKY_CMDS)
+        deny :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        WRITE_TOOLS.each { |t| confirm t }
+        # 📂 Sandbox dirs: always writable, even in production
+        WRITE_TOOLS.each { |t| allow t, when: path(*SANDBOX_DIRS) }
+        confirm :run_command
+      end
+    end
+
+    # ⚖️ Default — balanced: allow reads + writes, confirm dangerous shell, protect sensitive files.
+    # Best for: day-to-day development, pair programming with an agent.
+    def self.default
+      define do
+        deny_all
+        READONLY_TOOLS.each { |t| allow t }
+        WRITE_TOOLS.each { |t| allow t }
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+        allow :run_command
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        confirm :run_command, when: cmd(*RISKY_CMDS)
+        confirm :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+      end
+    end
+
+    # 🚀 Turbo — wide open with seatbelts: allow everything, only hard-deny catastrophic.
+    # Best for: trusted dev environments, rapid prototyping.
+    def self.turbo
+      define do
+        allow_all
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        confirm :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+      end
+    end
+
+    # 🧪 Test — permissive for test runners, but sandboxed.
+    # Best for: CI, test suites, RAILS_ENV=test.
+    def self.test
+      define do
+        allow_all
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        deny :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        confirm :run_command, when: cmd(*RISKY_CMDS)
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+      end
+    end
+
+    # 🔮 Auto — reads RAILS_ENV, RACK_ENV, or ANTIGRAVITY_ENV and picks a preset.
+    # Falls back to :default if unrecognized or unset.
+    def self.auto
+      env = ENV['ANTIGRAVITY_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
+      preset_name = ENV_MAP.fetch(env.to_s.downcase, :default)
+      send(preset_name)
+    end
+
+    # ------------------------------------------------------------------
+    # DSL methods
+    # ------------------------------------------------------------------
+
+    def allow(tool_name = nil, **kwargs)
+      @rules << Rule.new(:allow, tool_name, condition: kwargs[:when])
+    end
+
+    def deny(tool_name = nil, **kwargs)
+      @rules << Rule.new(:deny, tool_name, condition: kwargs[:when])
+    end
+
+    def confirm(tool_name = nil, **kwargs, &block)
+      @rules << Rule.new(:confirm, tool_name, condition: kwargs[:when], handler: block)
+    end
+
+    def allow_all
+      allow(nil)
+    end
+
+    def deny_all
+      deny(nil)
+    end
+
+    def on_confirm(&block)
+      @confirm_handler = block
+    end
+
+    # ------------------------------------------------------------------
+    # Predicate helpers
+    # ------------------------------------------------------------------
+
+    def cmd(*patterns)
+      ->(ctx) do
+        args = ctx[:args]
+        cmd_arg = args[:command_line] || args['command_line'] || args[:CommandLine] || args['CommandLine']
+        return false unless cmd_arg
+
+        cmd_arg = cmd_arg.to_s
+        patterns.any? { |p| cmd_arg.include?(p.to_s) }
+      end
+    end
+
+    def path(*globs)
+      ->(ctx) do
+        args = ctx[:args]
+        path_arg = args[:path] || args['path'] ||
+                   args[:file] || args['file'] ||
+                   args[:target] || args['target'] ||
+                   args[:file_path] || args['file_path'] ||
+                   args[:target_file] || args['target_file']
+        return false unless path_arg
+
+        path_arg = path_arg.to_s
+        globs.any? { |g| File.fnmatch?(g.to_s, path_arg) }
+      end
+    end
+
+    def args_match(**matchers)
+      ->(ctx) do
+        args = ctx[:args]
+        matchers.any? do |k, v|
+          val = args[k.to_sym] || args[k.to_s]
+          val && v.match?(val.to_s)
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Evaluation engine
+    # ------------------------------------------------------------------
+
+    def evaluate(tool_name, args = {})
+      matching_rules = @rules.select { |r| r.matches?(tool_name, args) }
+      best_rule = matching_rules.max_by(&:precedence)
+
+      if best_rule
+        if best_rule.action == :confirm
+          handler = best_rule.handler || @confirm_handler
+          if handler
+            ctx = { name: tool_name, args: args }
+            result = handler.call(ctx)
+            { status: result ? :allow : :deny }
+          else
+            { status: :deny }
+          end
+        elsif best_rule.action == :deny
+          { status: :deny, reason: "Denied by policy" }
+        else
+          { status: :allow }
+        end
+      else
+        { status: :deny } # Default to deny if no rules match
+      end
+    end
+  end
+end

data/lib/antigravity/protocol.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+
+module Antigravity
+  # Hand-rolled protobuf encoding/decoding for the 2 stdio handshake messages:
+  #   InputConfig  (SDK → localharness via stdin)
+  #   OutputConfig (localharness → SDK via stdout)
+  #
+  # Uses raw protobuf wire format to avoid the google-protobuf gem dependency.
+  # See: https://github.com/palladius/antigravity-ruby-sdk/issues/7
+  #
+  # Wire format reference: https://protobuf.dev/programming-guides/encoding/
+  #   Varint:           wire type 0, tag = (field_number << 3) | 0
+  #   Length-delimited: wire type 2, tag = (field_number << 3) | 2
+  class Protocol
+    # --- Encoding: InputConfig ---
+    # message InputConfig {
+    #   string storage_directory = 1;
+    #   uint32 port = 2;           # optional, we leave 0
+    #   string bind_address = 3;   # default "localhost"
+    #   ClientInfo client_info = 4;
+    #   map<string, string> env = 5;
+    # }
+    # message ClientInfo {
+    #   string language = 1;
+    #   string version = 2;
+    #   string language_version = 3;
+    #   string os = 4;
+    #   string os_version = 5;
+    # }
+    def self.encode_input_config(storage_directory:, bind_address: 'localhost', env: {})
+      buf = ''.b
+
+      # field 1: storage_directory (string)
+      buf << encode_string_field(1, storage_directory)
+
+      # field 3: bind_address (string, default "localhost")
+      buf << encode_string_field(3, bind_address)
+
+      # field 4: client_info (embedded message)
+      client_info = encode_client_info
+      buf << encode_bytes_field(4, client_info)
+
+      # field 5: env map entries (each is an embedded message with key=1, value=2)
+      env.each do |key, value|
+        entry = encode_string_field(1, key.to_s) + encode_string_field(2, value.to_s)
+        buf << encode_bytes_field(5, entry)
+      end
+
+      # Length-prefix: 4-byte little-endian uint32
+      [buf.bytesize].pack('V') + buf
+    end
+
+    # --- Decoding: OutputConfig ---
+    # message OutputConfig {
+    #   int32  port = 1;
+    #   string api_key = 2;
+    # }
+    def self.decode_output_config(data)
+      raise ProtocolError, 'Data too short for length prefix' if data.bytesize < 4
+
+      declared_len = data[0..3].unpack1('V')
+      payload = data[4..]
+
+      raise ProtocolError, "Truncated payload: expected #{declared_len}, got #{payload&.bytesize || 0}" if payload.nil? || payload.bytesize < declared_len
+
+      result = { port: 0, api_key: '' }
+      pos = 0
+
+      while pos < declared_len
+        tag_byte, new_pos = decode_varint(payload, pos)
+        pos = new_pos
+        field_number = tag_byte >> 3
+        wire_type = tag_byte & 0x07
+
+        case wire_type
+        when 0 # varint
+          value, pos = decode_varint(payload, pos)
+          result[:port] = value if field_number == 1
+        when 2 # length-delimited
+          length, pos = decode_varint(payload, pos)
+          value = payload[pos, length]
+          pos += length
+          result[:api_key] = value.force_encoding('UTF-8') if field_number == 2
+        else
+          raise ProtocolError, "Unsupported wire type #{wire_type} at position #{pos}"
+        end
+      end
+
+      result
+    end
+
+    # Read a length-prefixed frame from an IO (blocking).
+    # Returns the raw payload bytes.
+    def self.read_length_prefixed(io, timeout: 10)
+      len_bytes = read_exactly(io, 4, timeout: timeout)
+      raise ProtocolError, 'EOF reading length prefix' unless len_bytes&.bytesize == 4
+
+      payload_len = len_bytes.unpack1('V')
+      raise ProtocolError, "Unreasonable payload length: #{payload_len}" if payload_len > 1_000_000
+
+      frame = [payload_len].pack('V') + read_exactly(io, payload_len, timeout: timeout)
+      frame
+    end
+
+    class << self
+      private
+
+      def encode_client_info
+        buf = ''.b
+        buf << encode_string_field(1, 'ruby')
+        buf << encode_string_field(2, Antigravity::VERSION)
+        buf << encode_string_field(3, RUBY_VERSION)
+        buf << encode_string_field(4, ruby_platform_os)
+        buf << encode_string_field(5, RUBY_PLATFORM)
+        buf
+      end
+
+      def ruby_platform_os
+        case RUBY_PLATFORM
+        when /darwin/i then 'macos'
+        when /linux/i  then 'linux'
+        when /win/i    then 'windows'
+        else RUBY_PLATFORM
+        end
+      end
+
+      # Encode a string field: tag + varint length + UTF-8 bytes
+      def encode_string_field(field_number, value)
+        encode_bytes_field(field_number, value.to_s.encode('UTF-8').b)
+      end
+
+      # Encode a length-delimited field: tag + varint length + raw bytes
+      def encode_bytes_field(field_number, bytes)
+        tag = (field_number << 3) | 2 # wire type 2 = length-delimited
+        encode_varint_bytes(tag) + encode_varint_bytes(bytes.bytesize) + bytes
+      end
+
+      # Encode an integer as varint bytes
+      def encode_varint_bytes(value)
+        bytes = []
+        loop do
+          byte = value & 0x7F
+          value >>= 7
+          byte |= 0x80 if value > 0
+          bytes << byte
+          break if value == 0
+        end
+        bytes.pack('C*')
+      end
+
+      # Decode a varint starting at position, returns [value, new_position]
+      def decode_varint(data, pos)
+        result = 0
+        shift = 0
+        loop do
+          raise ProtocolError, "Varint extends past end of data at pos #{pos}" if pos >= data.bytesize
+
+          byte = data.getbyte(pos)
+          pos += 1
+          result |= (byte & 0x7F) << shift
+          break if (byte & 0x80) == 0
+
+          shift += 7
+          raise ProtocolError, 'Varint too long' if shift >= 64
+        end
+        [result, pos]
+      end
+
+      # Read exactly n bytes from IO with timeout
+      def read_exactly(io, n, timeout: 10)
+        buf = ''.b
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        while buf.bytesize < n
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise ProtocolError, "Timeout reading #{n} bytes from harness" if remaining <= 0
+
+          ready = IO.select([io], nil, nil, [remaining, 0.1].min)
+          if ready
+            chunk = io.read_nonblock(n - buf.bytesize, exception: false)
+            case chunk
+            when String then buf << chunk
+            when :wait_readable then next
+            when nil then raise ProtocolError, 'EOF while reading from harness'
+            end
+          end
+        end
+        buf
+      end
+    end
+  end
+end

data/lib/antigravity/skill.rb

@@ -3,30 +3,78 @@
 require "yaml"
 
 module Antigravity
+  # Represents an Agent Skill loaded from a SKILL.md file or defined inline.
+  # Spec: https://agentskills.io/specification
+  #
+  # A skill directory must contain a SKILL.md with YAML frontmatter:
+  #   ---
+  #   name: my-skill
+  #   description: What this skill does
+  #   ---
+  #   # Instructions in markdown...
   class Skill < Base
 
-    attr_reader :name, :description, :instructions, :path
+    attr_reader :name, :description, :instructions, :path, :metadata
 
+    # Load a skill from a directory containing SKILL.md.
+    # @param path [String] path to skill directory
     def initialize(path)
       @path = File.expand_path(path)
+      @metadata = {}
       parse_skill_file
     end
 
+    # Factory: load from directory path.
     def self.load(path)
       new(path)
     end
 
+    # Factory: create an inline skill (no file needed).
+    # @param name [String] skill name (lowercase, hyphenated)
+    # @param description [String] what the skill does
+    # @param instructions [String] the skill instructions (markdown)
+    # @return [Skill] an inline skill instance
+    def self.inline(name:, description:, instructions:)
+      skill = allocate
+      skill.send(:init_inline, name: name, description: description, instructions: instructions)
+      skill
+    end
+
+    # Check if a directory is a valid skill (contains SKILL.md).
+    # @param path [String] directory path to check
+    # @return [Boolean]
+    def self.skill_dir?(path)
+      SkillResolver.skill_dir?(path)
+    end
+
+    def to_s
+      "#<Skill name=#{@name.inspect} path=#{@path.inspect}>"
+    end
+
+    def inspect
+      "#<Antigravity::Skill name=#{@name.inspect} description=#{@description.inspect} path=#{@path.inspect}>"
+    end
+
     private
 
+    def init_inline(name:, description:, instructions:)
+      @name = name
+      @description = description
+      @instructions = instructions
+      @path = nil  # inline skills have no path
+      @metadata = {}
+    end
+
     def parse_skill_file
       skill_file = File.join(@path, "SKILL.md")
       raise ArgumentError, "SKILL.md not found at #{@path}" unless File.exist?(skill_file)
 
-      content = File.read(skill_file)
+      content = File.read(skill_file, encoding: 'UTF-8')
       if content =~ /\A(---\s*\n.*?\n?)^(---\s*$\n?)/m
-        front_matter = YAML.safe_load(Regexp.last_match(1))
-        @name = front_matter["name"]
-        @description = front_matter["description"]
+        front_matter = YAML.safe_load(Regexp.last_match(1)) || {}
+        @name = front_matter["name"] || File.basename(@path)
+        @description = front_matter["description"] || ""
+        @metadata = front_matter.fetch("metadata", {})
         @instructions = Regexp.last_match.post_match.strip
       else
         @name = File.basename(@path)

data/lib/antigravity/skill_resolver.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Antigravity
+  # Resolves skill paths from various inputs: single skill dir, container dir,
+  # or GitHub URL. Returns expanded absolute paths to skill directories.
+  #
+  # Resolution logic:
+  #   1. Path contains SKILL.md -> single skill
+  #   2. Path has a skills/ subfolder -> discover children with SKILL.md
+  #   3. Path children have SKILL.md -> flat container discovery
+  #   4. GitHub URL -> clone/cache then resolve locally
+  #
+  # Spec compliance: https://agentskills.io/specification
+  class SkillResolver
+    GITHUB_URL_PATTERN = %r{\Ahttps?://github\.com/}i
+    CACHE_DIR = File.expand_path('~/.antigravity/cache/ruby-sdk/skills')
+
+    # Resolve a path or URL to an array of valid skill directory paths.
+    # @param path_or_url [String] local path or GitHub URL
+    # @return [Array<String>] expanded absolute paths to skill directories
+    def self.resolve(path_or_url)
+      path_or_url = path_or_url.to_s.strip
+
+      if github_url?(path_or_url)
+        resolve_github(path_or_url)
+      else
+        resolve_local(path_or_url)
+      end
+    end
+
+    # Discover all skill directories inside a container path.
+    # Checks for skills/ subfolder first, then scans children directly.
+    # @param container_path [String] path to scan for skills
+    # @return [Array<String>] sorted list of skill directory paths
+    def self.discover(container_path)
+      expanded = File.expand_path(container_path)
+      return [] unless File.directory?(expanded)
+
+      # Check for skills/ subfolder first (convention from agentskills.io)
+      skills_subdir = File.join(expanded, 'skills')
+      scan_dir = File.directory?(skills_subdir) ? skills_subdir : expanded
+
+      Dir.children(scan_dir)
+         .map { |child| File.join(scan_dir, child) }
+         .select { |child_path| skill_dir?(child_path) }
+         .sort
+    end
+
+    # Check if a directory is a valid skill (contains SKILL.md).
+    # @param path [String] directory path to check
+    # @return [Boolean]
+    def self.skill_dir?(path)
+      File.directory?(path) && File.exist?(File.join(path, 'SKILL.md'))
+    end
+
+    # Check if a string looks like a GitHub URL.
+    # @param str [String]
+    # @return [Boolean]
+    def self.github_url?(str)
+      str.match?(GITHUB_URL_PATTERN)
+    end
+
+    class << self
+      private
+
+      def resolve_local(path)
+        expanded = File.expand_path(path)
+        raise ArgumentError, "Skill path does not exist: #{expanded}" unless File.exist?(expanded)
+        raise ArgumentError, "Skill path is not a directory: #{expanded}" unless File.directory?(expanded)
+
+        # Case 1: Direct skill dir (has SKILL.md)
+        return [expanded] if skill_dir?(expanded)
+
+        # Case 2 & 3: Container dir -- discover children
+        discovered = discover(expanded)
+        return discovered unless discovered.empty?
+
+        raise ArgumentError, "No skills found at #{expanded}. Expected SKILL.md or a skills/ subfolder."
+      end
+
+      # Parse a GitHub URL into components.
+      # Supports:
+      #   https://github.com/org/repo
+      #   https://github.com/org/repo/tree/main/skills/my-skill
+      #   https://github.com/org/repo/tree/main/skills
+      #
+      # Returns [org, repo, subpath_or_nil]
+      def parse_github_url(url)
+        # Strip trailing slash
+        url = url.chomp('/')
+
+        case url
+        when %r{github\.com/([^/]+)/([^/]+)/tree/[^/]+/(.+)}
+          # URL with tree/branch/subpath
+          [Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3)]
+        when %r{github\.com/([^/]+)/([^/]+)(?:\.git)?/?$}
+          # Bare repo URL
+          [Regexp.last_match(1), Regexp.last_match(2), nil]
+        when %r{github\.com/([^/]+)/([^/]+)/(.+)}
+          # URL with subpath but no /tree/branch/ (e.g. from skill_name:)
+          [Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3)]
+        else
+          raise ArgumentError, "Cannot parse GitHub URL: #{url}"
+        end
+      end
+
+      def resolve_github(url)
+        org, repo, subpath = parse_github_url(url)
+        local_repo = clone_or_update(org, repo)
+
+        # Resolve subpath within the cloned repo
+        target = subpath ? File.join(local_repo, subpath) : local_repo
+        resolve_local(target)
+      end
+
+      # Clone (or update) a GitHub repo into the cache.
+      # Returns the local path to the cloned repo.
+      def clone_or_update(org, repo)
+        cache_path = File.join(CACHE_DIR, org, repo)
+
+        if File.directory?(File.join(cache_path, '.git'))
+          # Already cloned -- pull latest
+          system('git', '-C', cache_path, 'pull', '--ff-only', '--quiet',
+                 out: File::NULL, err: File::NULL)
+        else
+          # Fresh clone
+          FileUtils.mkdir_p(File.dirname(cache_path))
+          clone_url = "https://github.com/#{org}/#{repo}.git"
+          success = system('git', 'clone', '--depth=1', '--quiet', clone_url, cache_path,
+                           out: File::NULL, err: File::NULL)
+          raise "Failed to clone #{clone_url}. Check the URL and your network." unless success
+        end
+
+        cache_path
+      end
+    end
+  end
+end