Feature: Devcontainer handler content operations coverage
  As a developer maintaining DevcontainerHandler
  I want thorough BDD tests for read, write, discover_children, and _exec_ls
  So that uncovered lines 223-348 are exercised and regressions are caught

  # ── read() method (lines 223-238) ──────────────────────────

  Scenario: dccov3 read file successfully from devcontainer
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful cat output "hello world"
    When dccov3 I read path "src/main.py" from the resource
    Then dccov3 the read should succeed with data "hello world"
    And dccov3 the subprocess should have been called with command containing "cat" and "src/main.py"

  Scenario: dccov3 read with empty path delegates to exec_ls
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls output "dir1\ndir2\nfile.txt"
    When dccov3 I read with an empty path from the resource
    Then dccov3 the read should succeed with data "dir1\ndir2\nfile.txt"
    And dccov3 the subprocess should have been called with command containing "ls" and "."

  Scenario: dccov3 read file with non-zero returncode raises FileNotFoundError
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns failed cat output with stderr "No such file"
    When dccov3 I read path "missing.txt" from the resource
    Then dccov3 the read should raise FileNotFoundError containing "missing.txt"

  Scenario: dccov3 read from resource with no location raises ValueError
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with no location
    When dccov3 I read path "any/file.txt" from the resource
    Then dccov3 the read should raise ValueError containing "no location"

  # ── write() method (lines 254-280) ─────────────────────────

  Scenario: dccov3 write file successfully to devcontainer
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful tee output
    When dccov3 I write path "output.txt" with data "new content" to the resource
    Then dccov3 the write should succeed with bytes_written 11
    And dccov3 the write message should contain "output.txt"
    And dccov3 the subprocess should have been called with command containing "tee" and "output.txt"

  Scenario: dccov3 write file with non-zero returncode returns failure
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns failed tee output with stderr "Permission denied"
    When dccov3 I write path "readonly.txt" with data "data" to the resource
    Then dccov3 the write should fail
    And dccov3 the write failure message should contain "Permission denied"

  Scenario: dccov3 write to resource with no location raises ValueError
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with no location
    When dccov3 I write path "any.txt" with data "x" to the resource
    Then dccov3 the write should raise ValueError containing "no location"

  # ── discover_children() method (lines 294-328) ─────────────

  Scenario: dccov3 discover children lists directories from devcontainer
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls listing "src\ntests\nREADME.md"
    When dccov3 I discover children of the resource
    Then dccov3 the children list should have 3 entries
    And dccov3 the first child should have name "README.md"
    And dccov3 the second child should have name "src"
    And dccov3 the third child should have name "tests"
    And dccov3 each child should have type "fs-directory"
    And dccov3 each child location should start with "/ws/project/"

  Scenario: dccov3 discover children returns empty on subprocess failure
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns failed ls output
    When dccov3 I discover children of the resource
    Then dccov3 the children list should have 0 entries

  Scenario: dccov3 discover children on resource with no location raises ValueError
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with no location
    When dccov3 I discover children of the resource
    Then dccov3 discover children should raise ValueError containing "no location"

  Scenario: dccov3 discover children filters blank lines from ls output
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls listing "alpha\n\n\nbeta\n"
    When dccov3 I discover children of the resource
    Then dccov3 the children list should have 2 entries
    And dccov3 the first child should have name "alpha"
    And dccov3 the second child should have name "beta"

  Scenario: dccov3 discover children sets correct parent reference
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls listing "lib"
    When dccov3 I discover children of the resource
    Then dccov3 each child should reference the parent resource id

  # ── _exec_ls() via read empty path (lines 333-348) ─────────

  Scenario: dccov3 exec_ls with successful subprocess returns stdout
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls output "file1\nfile2"
    When dccov3 I read with an empty path from the resource
    Then dccov3 the read should succeed with data "file1\nfile2"

  Scenario: dccov3 exec_ls with failed subprocess returns empty content
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns failed ls for exec_ls
    When dccov3 I read with an empty path from the resource
    Then dccov3 the read should succeed with empty data

  # ── write with subprocess input validation ──────────────────

  Scenario: dccov3 write passes data bytes as subprocess input
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful tee output
    When dccov3 I write path "data.bin" with bytes to the resource
    Then dccov3 the subprocess should have received input bytes

  Scenario: dccov3 discover children child description includes resource id
    Given dccov3 a devcontainer handler
    And dccov3 a devcontainer-instance resource with location "/ws/project"
    And dccov3 subprocess returns successful ls listing "docs"
    When dccov3 I discover children of the resource
    Then dccov3 each child description should mention the parent resource id