freemo
279c6112ae
CI / benchmark-publish (pull_request) Has been skipped
CI / lint (pull_request) Successful in 15s
CI / build (pull_request) Successful in 17s
CI / quality (pull_request) Successful in 17s
CI / security (pull_request) Successful in 34s
CI / typecheck (pull_request) Successful in 34s
CI / unit_tests (pull_request) Successful in 1m48s
CI / docker (pull_request) Successful in 39s
CI / integration_tests (pull_request) Successful in 3m26s
CI / coverage (pull_request) Successful in 4m15s
CI / lint (push) Successful in 13s
CI / quality (push) Successful in 17s
CI / typecheck (push) Successful in 31s
CI / security (push) Successful in 31s
CI / benchmark-regression (push) Has been skipped
CI / build (push) Successful in 17s
CI / unit_tests (push) Successful in 3m1s
CI / integration_tests (push) Successful in 4m28s
CI / docker (push) Successful in 1m1s
CI / coverage (push) Successful in 4m33s
CI / benchmark-publish (push) Successful in 14m26s
CI / benchmark-regression (pull_request) Successful in 25m42s
Added three new built-in resource types: container-instance, devcontainer-instance, and devcontainer-file. The devcontainer-instance type inherits from container-instance per ADR-042 and is auto-discovered when git-checkout or fs-directory resources contain .devcontainer/ directories per ADR-043. Implementation includes: - DevcontainerHandler extending BaseResourceHandler with snapshot strategy - Auto-discovery module scanning .devcontainer/devcontainer.json and root .devcontainer.json with JSON validation - CLI support for devcontainer-instance and container-instance via agents resource add with --path and --image flags - Behave feature with 22 scenarios covering manual registration, auto-discovery, invalid JSON handling, and protocol conformance - Robot integration tests with 10 test cases for CLI round-trip and DAG hierarchy validation - ASV benchmarks measuring discovery throughput with varying subdirectory counts, handler resolver cache performance, and result construction - Reference documentation at docs/reference/devcontainer_resources.md ISSUES CLOSED: #511
138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
# Devcontainer Resources
|
|
|
|
Devcontainer resources integrate the
|
|
[Development Containers Specification](https://containers.dev) into the
|
|
CleverAgents resource model. Two resource types and an auto-discovery
|
|
mechanism allow CleverAgents to detect, register, and use devcontainer
|
|
environments automatically.
|
|
|
|
## Resource Types
|
|
|
|
### `devcontainer-instance`
|
|
|
|
A container execution environment defined by a
|
|
`.devcontainer/devcontainer.json` configuration file. Inherits from
|
|
`container-instance` (see ADR-042 for resource type inheritance).
|
|
|
|
| Property | Value |
|
|
|-------------------|-----------------------|
|
|
| Kind | physical |
|
|
| Sandbox strategy | snapshot |
|
|
| User-addable | yes |
|
|
| Parent types | git-checkout, fs-directory |
|
|
| Child types | devcontainer-file |
|
|
| Handler | `DevcontainerHandler` |
|
|
|
|
**CLI arguments:**
|
|
|
|
- `--path` (path, required): Path to the directory containing
|
|
`.devcontainer/devcontainer.json`.
|
|
|
|
### `devcontainer-file`
|
|
|
|
A single-file resource pointing to the `devcontainer.json`
|
|
configuration file itself. Created automatically as a child of
|
|
`devcontainer-instance` during auto-discovery.
|
|
|
|
| Property | Value |
|
|
|-------------------|-----------------------|
|
|
| Kind | physical |
|
|
| Sandbox strategy | copy\_on\_write |
|
|
| User-addable | no |
|
|
| Parent types | devcontainer-instance |
|
|
| Child types | (none) |
|
|
| Handler | `DevcontainerHandler` |
|
|
|
|
### `container-instance`
|
|
|
|
The base container resource type from which `devcontainer-instance`
|
|
inherits. Represents a generic container execution environment.
|
|
|
|
| Property | Value |
|
|
|-------------------|-----------------------|
|
|
| Kind | physical |
|
|
| Sandbox strategy | snapshot |
|
|
| User-addable | yes |
|
|
| Parent types | git-checkout, fs-directory |
|
|
| Child types | (none) |
|
|
| Handler | `DevcontainerHandler` |
|
|
|
|
## Auto-Discovery
|
|
|
|
When a `git-checkout` or `fs-directory` resource is linked to a
|
|
project, the auto-discovery hook scans for devcontainer configurations
|
|
in the following locations (relative to the resource root):
|
|
|
|
1. `.devcontainer/devcontainer.json`
|
|
2. `.devcontainer.json` (root-level)
|
|
|
|
### Discovery Process
|
|
|
|
1. **Trigger**: Linking a `git-checkout` or `fs-directory` resource.
|
|
2. **Scan**: The discovery module checks for configuration files at the
|
|
well-known paths listed above.
|
|
3. **Validate**: Each discovered file is parsed as JSON. Invalid files
|
|
are skipped with a warning.
|
|
4. **Register**: For each valid configuration:
|
|
- A `devcontainer-instance` child resource is created under the
|
|
parent resource.
|
|
- A `devcontainer-file` child resource is created under the
|
|
devcontainer instance, pointing to the JSON file.
|
|
|
|
### Lazy Activation
|
|
|
|
Devcontainers use lazy activation: the container is only built and
|
|
started when first needed by a plan execution. The discovery phase
|
|
only registers the resource metadata.
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
# Manually add a devcontainer instance
|
|
agents resource add devcontainer-instance local/my-dc --path /home/user/project
|
|
|
|
# Add a container instance
|
|
agents resource add container-instance local/my-ctr --image ubuntu:latest
|
|
|
|
# List all devcontainer resources
|
|
agents resource list --type devcontainer-instance
|
|
|
|
# Show devcontainer details
|
|
agents resource show local/my-dc
|
|
|
|
# View resource tree (shows devcontainer children)
|
|
agents resource tree local/my-repo
|
|
|
|
# Inspect resource with tree view
|
|
agents resource inspect local/my-repo --tree
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The devcontainer integration follows ADR-043 and builds on the
|
|
resource type inheritance model defined in ADR-042.
|
|
|
|
### Handler
|
|
|
|
`DevcontainerHandler` extends `BaseResourceHandler` and uses the
|
|
`snapshot` sandbox strategy. It handles both `devcontainer-instance`
|
|
and `devcontainer-file` resource types through the common base class
|
|
resolve logic.
|
|
|
|
### Discovery Module
|
|
|
|
The `cleveragents.resource.handlers.discovery` module provides:
|
|
|
|
- `discover_devcontainers(location, type)`: Scans a path for
|
|
devcontainer configs.
|
|
- `is_trigger_type(type)`: Checks if a resource type triggers
|
|
auto-discovery.
|
|
- `DevcontainerDiscoveryResult`: Data class holding discovery results.
|
|
|
|
## See Also
|
|
|
|
- [ADR-042: Resource Type Inheritance](../adr/ADR-042-resource-type-inheritance.md)
|
|
- [ADR-043: Devcontainer Integration](../adr/ADR-043-devcontainer-integration.md)
|
|
- [Resource Types (Built-in)](resource_types_builtin.md)
|
|
- [Resource Handlers](resource_handlers.md)
|