cleveragents-core/features/resource_handlers.feature

Feature: Resource handler runtime
  As a developer
  I want resource handlers that resolve resources into sandbox-backed paths
  So that tools receive isolated working directories during plan execution

  # === Handler Protocol ===

  Scenario: GitCheckoutHandler satisfies ResourceHandler protocol
    Then GitCheckoutHandler should satisfy the ResourceHandler protocol

  Scenario: FsDirectoryHandler satisfies ResourceHandler protocol
    Then FsDirectoryHandler should satisfy the ResourceHandler protocol

  # === GitCheckoutHandler ===

  Scenario: GitCheckoutHandler resolves a git-checkout resource
    Given a git-checkout resource with location "/tmp/test-repo"
    And a sandbox manager with a mock factory
    When I resolve the resource with GitCheckoutHandler for plan "PLAN001"
    Then the bound resource should have slot name "repo"
    And the bound resource should have resource type "git-checkout"
    And the bound resource sandbox path should not be empty

  Scenario: GitCheckoutHandler uses resource-level strategy override
    Given a git-checkout resource at "/tmp/test-repo" using strategy "copy_on_write"
    And a sandbox manager with a mock factory
    When I resolve the resource with GitCheckoutHandler for plan "PLAN002"
    Then the sandbox was created with strategy "copy_on_write"

  Scenario: GitCheckoutHandler rejects resource without location
    Given a git-checkout resource without location
    And a sandbox manager with a mock factory
    When I try to resolve the resource with GitCheckoutHandler
    Then a handler ValueError should be raised
    And the handler error should mention "no location"

  # === FsDirectoryHandler ===

  Scenario: FsDirectoryHandler resolves an fs-directory resource
    Given an fs-directory resource with location "/tmp/test-dir"
    And a sandbox manager with a mock factory
    When I resolve the resource with FsDirectoryHandler for plan "PLAN003"
    Then the bound resource should have slot name "workdir"
    And the bound resource should have resource type "fs-directory"
    And the bound resource sandbox path should not be empty

  Scenario: FsDirectoryHandler uses copy_on_write by default
    Given an fs-directory resource with location "/tmp/test-dir"
    And a sandbox manager with a mock factory
    When I resolve the resource with FsDirectoryHandler for plan "PLAN004"
    Then the sandbox was created with strategy "copy_on_write"

  Scenario: FsDirectoryHandler rejects resource without location
    Given an fs-directory resource without location
    And a sandbox manager with a mock factory
    When I try to resolve the resource with FsDirectoryHandler
    Then a handler ValueError should be raised

  # === Handler Resolver ===

  Scenario: Resolve handler from valid module:class string
    When I resolve handler "cleveragents.resource.handlers.git_checkout:GitCheckoutHandler"
    Then the resolved handler should be a GitCheckoutHandler instance

  Scenario: Resolve handler from fs-directory reference
    When I resolve handler "cleveragents.resource.handlers.fs_directory:FsDirectoryHandler"
    Then the resolved handler should be a FsDirectoryHandler instance

  Scenario: Resolve handler caches instances
    When I resolve handler "cleveragents.resource.handlers.git_checkout:GitCheckoutHandler"
    And I resolve the same handler reference again
    Then both resolved handlers should be the same object

  Scenario: Resolve handler rejects empty string
    When I try to resolve an empty handler reference
    Then a HandlerResolutionError should be raised
    And the resolution error should mention "empty"

  Scenario: Resolve handler rejects missing colon separator
    When I try to resolve handler "cleveragents.resource.handlers.git_checkout"
    Then a HandlerResolutionError should be raised
    And the resolution error should mention "module.path:ClassName"

  Scenario: Resolve handler rejects nonexistent module
    When I try to resolve handler "nonexistent.module:SomeClass"
    Then a HandlerResolutionError should be raised
    And the resolution error should mention "Cannot import"

  Scenario: Resolve handler rejects nonexistent class in valid module
    When I try to resolve handler "cleveragents.resource.handlers.git_checkout:NonExistentClass"
    Then a HandlerResolutionError should be raised
    And the resolution error should mention "not found"

  # === ResourceHandlerService ===

  Scenario: ResourceHandlerService resolves a binding to BoundResource
    Given a resource handler service with mock lookups
    And a binding result for slot "repo" with resource id "RES001"
    When I resolve the binding via resource handler service for plan "PLAN010"
    Then the handler service should return a BoundResource
    And the handler service BoundResource slot should be "repo"
    And the handler service BoundResource sandbox path should not be empty

  Scenario: ResourceHandlerService skips deferred bindings
    Given a resource handler service with mock lookups
    And a deferred binding result for slot "extra"
    And a binding result for slot "repo" with resource id "RES001"
    When I resolve all bindings via resource handler service for plan "PLAN011"
    Then the handler service should return 1 bound resource
    And the handler service should have resolved slot "repo"

  Scenario: ResourceHandlerService rejects deferred single binding
    Given a resource handler service with mock lookups
    And a deferred binding result for slot "extra"
    When I try to resolve the single deferred binding via resource handler service
    Then a handler ValueError should be raised
    And the handler error should mention "deferred"

  Scenario: ResourceHandlerService uses fallback handler when type has no handler string
    Given a resource handler service with mock lookups and no handler string
    And a binding result for slot "data" with resource id "RES002"
    When I resolve the binding via resource handler service for plan "PLAN012"
    Then the handler service should return a BoundResource
    And the handler service BoundResource sandbox path should not be empty