feat(resource): implement ResourceHandler protocol methods (read/write/delete/list/diff/discover_children) #827

Closed
opened 2026-03-13 20:14:52 +00:00 by freemo · 0 comments
Owner

Metadata

  • Commit Message: feat(resource): implement ResourceHandler CRUD and discovery methods
  • Branch: feature/resource-handler-crud
  • Type: Feature
  • Priority: Medium
  • MoSCoW: Should have
  • Points: 13
  • Milestone: v3.6.0

Background and Context

The specification defines 12 methods on the ResourceHandler protocol (src/cleveragents/resource/handlers/protocol.py). Currently, only resolve() is implemented across the handler types (git-checkout, fs-directory, devcontainer, database). The remaining core CRUD and discovery methods are missing:

  • read(resource) -> Content — Read resource content
  • write(resource, content) -> WriteResult — Write/update resource content
  • delete(resource) -> DeleteResult — Remove a resource
  • list(parent) -> list[Resource] — List child resources
  • diff(resource, other) -> DiffResult — Compare two resource states
  • discover_children(resource) -> list[Resource] — Auto-discover child resources

These methods are essential for the apply pipeline to function (read current state, write changes, verify via diff) and for resource discovery to populate the resource DAG.

Acceptance Criteria

  • read() implemented for git-checkout (git show), fs-directory (file read), devcontainer (exec cat), database (query)
  • write() implemented for git-checkout (git apply), fs-directory (file write), devcontainer (exec write), database (execute)
  • delete() implemented for all handler types with appropriate cleanup
  • list() implemented for all handler types returning child resources
  • diff() implemented for git-checkout (git diff), fs-directory (file diff), with fallback for others
  • discover_children() implemented for git-checkout (git ls-tree), fs-directory (os.walk), devcontainer (exec ls)
  • All methods respect the handler's sandbox scope

Definition of Done

This issue is complete when:

  • All subtasks below are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Subtasks

  • Implement read() for git-checkout, fs-directory, devcontainer, database handlers
  • Implement write() for git-checkout, fs-directory, devcontainer, database handlers
  • Implement delete() for all handler types
  • Implement list() for all handler types
  • Implement diff() for git-checkout, fs-directory, with fallback
  • Implement discover_children() for git-checkout, fs-directory, devcontainer
  • Tests (Behave): Add scenarios for each method on each handler type
  • Tests (Robot): Add integration test for read → write → diff cycle
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors
## Metadata - **Commit Message**: `feat(resource): implement ResourceHandler CRUD and discovery methods` - **Branch**: `feature/resource-handler-crud` - **Type**: Feature - **Priority**: Medium - **MoSCoW**: Should have - **Points**: 13 - **Milestone**: v3.6.0 ## Background and Context The specification defines 12 methods on the `ResourceHandler` protocol (`src/cleveragents/resource/handlers/protocol.py`). Currently, only `resolve()` is implemented across the handler types (git-checkout, fs-directory, devcontainer, database). The remaining core CRUD and discovery methods are missing: - `read(resource) -> Content` — Read resource content - `write(resource, content) -> WriteResult` — Write/update resource content - `delete(resource) -> DeleteResult` — Remove a resource - `list(parent) -> list[Resource]` — List child resources - `diff(resource, other) -> DiffResult` — Compare two resource states - `discover_children(resource) -> list[Resource]` — Auto-discover child resources These methods are essential for the apply pipeline to function (read current state, write changes, verify via diff) and for resource discovery to populate the resource DAG. ## Acceptance Criteria - [ ] `read()` implemented for git-checkout (git show), fs-directory (file read), devcontainer (exec cat), database (query) - [ ] `write()` implemented for git-checkout (git apply), fs-directory (file write), devcontainer (exec write), database (execute) - [ ] `delete()` implemented for all handler types with appropriate cleanup - [ ] `list()` implemented for all handler types returning child resources - [ ] `diff()` implemented for git-checkout (git diff), fs-directory (file diff), with fallback for others - [ ] `discover_children()` implemented for git-checkout (git ls-tree), fs-directory (os.walk), devcontainer (exec ls) - [ ] All methods respect the handler's sandbox scope ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. ## Subtasks - [ ] Implement `read()` for git-checkout, fs-directory, devcontainer, database handlers - [ ] Implement `write()` for git-checkout, fs-directory, devcontainer, database handlers - [ ] Implement `delete()` for all handler types - [ ] Implement `list()` for all handler types - [ ] Implement `diff()` for git-checkout, fs-directory, with fallback - [ ] Implement `discover_children()` for git-checkout, fs-directory, devcontainer - [ ] Tests (Behave): Add scenarios for each method on each handler type - [ ] Tests (Robot): Add integration test for read → write → diff cycle - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors
freemo added this to the v3.6.0 milestone 2026-03-13 20:20:00 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#827
No description provided.