refactor(cli): resource add should dynamically generate CLI flags from resource type cli_args definitions #1213

New issue

Open

opened 2026-03-31 00:43:27 +00:00 by freemo · 0 comments

freemo commented

2026-03-31 00:43:27 +00:00

Owner

Background and Context

The specification defines a cli_args system on resource types (spec lines 23615, 34371–34516) where each resource type declares its own CLI arguments as a structured array. The resource add command is supposed to dynamically build its type-specific flags from these declarations at runtime.

The spec says (line 10587):

"Type-specific flags depend on the resource type. See agents resource type show <TYPE> for available arguments."

And the cli_args JSON Schema (cliArg definition, spec lines 34485–34516) supports:

name (becomes --<name> on the CLI)
type (string, path, integer, boolean, url — with validation)
required (boolean)
description (shown in --help)
default (value when not provided)
validation_pattern (regex for string/url types)

Resource types also support inheritance of cli_args via the inherits field (ADR-042), with additive collection merging by default.

Current State (after PR #1192)

Flags like --path, --branch, --image, --mount, --clone-into, and --read-only are hardcoded as Python/Typer function parameters directly in src/cleveragents/cli/commands/resource.py. Container-specific flags are gated by a hardcoded _CONTAINER_TYPES frozenset.

Problems

Custom types can't surface their own flags. A user who registers a custom type via agents resource type add --config db-type.yaml with cli_args: [{name: connection-string, type: string, required: true}] will not get a --connection-string flag on agents resource add <type>. The spec explicitly supports this (spec lines 24341–24402 show a full example of a custom local/database type with custom CLI args).
Adding flags for new built-in types requires editing Python source. The type definition's cli_args array is effectively inert/decorative — the actual CLI behavior is determined by hardcoded Python, not by the type metadata.
Inheritance is not reflected. The spec shows devcontainer-instance inheriting cli_args from container-instance and adding its own --config-path (spec lines 23649–23667). The current code hardcodes a _CONTAINER_TYPES set instead of walking the inheritance chain.
agents resource type show <TYPE> displays CLI args from the type definition, but those args don't actually drive the CLI — creating a confusing disconnect between what's advertised and what works.

Acceptance Criteria

agents resource add <TYPE> dynamically generates type-specific flags from the resource type's cli_args definition
Built-in types (git-checkout, git, fs-mount, fs-directory, container-instance, devcontainer-instance) define their cli_args in their type definitions, not in Python function signatures
Custom types registered via agents resource type add automatically get their declared CLI args surfaced on agents resource add <type>
cli_args inheritance works: subtypes inherit parent args and can add/override per ADR-042
The hardcoded _CONTAINER_TYPES frozenset and per-type if branches in resource_add() are replaced by data-driven dispatch
Existing hardcoded flags (--path, --branch, --image, --mount, --clone-into, --read-only) continue to work via their type definitions
agents resource type show <TYPE> output matches the actual available CLI flags
Tests (Behave): scenarios covering dynamic flag generation for at least one built-in and one custom type

Spec References

Command synopsis: line 311 ([type-specific-flags...])
resource add detail: lines 10574–10594
Resource type cli_args definition: lines 23615, 34371–34516
cliArg JSON Schema: lines 34485–34516
Custom type example with cli_args: lines 24341–24402
Type inheritance with cli_args: lines 23636, 23649–23667
ADR-042: Resource Type Inheritance

## Background and Context The specification defines a `cli_args` system on resource types (spec lines 23615, 34371–34516) where each resource type declares its own CLI arguments as a structured array. The `resource add` command is supposed to dynamically build its type-specific flags from these declarations at runtime. The spec says (line 10587): > "Type-specific flags depend on the resource type. See `agents resource type show <TYPE>` for available arguments." And the `cli_args` JSON Schema (`cliArg` definition, spec lines 34485–34516) supports: - `name` (becomes `--<name>` on the CLI) - `type` (string, path, integer, boolean, url — with validation) - `required` (boolean) - `description` (shown in `--help`) - `default` (value when not provided) - `validation_pattern` (regex for string/url types) Resource types also support inheritance of `cli_args` via the `inherits` field (ADR-042), with additive collection merging by default. ### Current State (after PR #1192) Flags like `--path`, `--branch`, `--image`, `--mount`, `--clone-into`, and `--read-only` are **hardcoded** as Python/Typer function parameters directly in `src/cleveragents/cli/commands/resource.py`. Container-specific flags are gated by a hardcoded `_CONTAINER_TYPES` frozenset. ### Problems 1. **Custom types can't surface their own flags.** A user who registers a custom type via `agents resource type add --config db-type.yaml` with `cli_args: [{name: connection-string, type: string, required: true}]` will not get a `--connection-string` flag on `agents resource add <type>`. The spec explicitly supports this (spec lines 24341–24402 show a full example of a custom `local/database` type with custom CLI args). 2. **Adding flags for new built-in types requires editing Python source.** The type definition's `cli_args` array is effectively inert/decorative — the actual CLI behavior is determined by hardcoded Python, not by the type metadata. 3. **Inheritance is not reflected.** The spec shows `devcontainer-instance` inheriting `cli_args` from `container-instance` and adding its own `--config-path` (spec lines 23649–23667). The current code hardcodes a `_CONTAINER_TYPES` set instead of walking the inheritance chain. 4. **`agents resource type show <TYPE>` displays CLI args from the type definition**, but those args don't actually drive the CLI — creating a confusing disconnect between what's advertised and what works. ## Acceptance Criteria - [ ] `agents resource add <TYPE>` dynamically generates type-specific flags from the resource type's `cli_args` definition - [ ] Built-in types (`git-checkout`, `git`, `fs-mount`, `fs-directory`, `container-instance`, `devcontainer-instance`) define their `cli_args` in their type definitions, not in Python function signatures - [ ] Custom types registered via `agents resource type add` automatically get their declared CLI args surfaced on `agents resource add <type>` - [ ] `cli_args` inheritance works: subtypes inherit parent args and can add/override per ADR-042 - [ ] The hardcoded `_CONTAINER_TYPES` frozenset and per-type `if` branches in `resource_add()` are replaced by data-driven dispatch - [ ] Existing hardcoded flags (`--path`, `--branch`, `--image`, `--mount`, `--clone-into`, `--read-only`) continue to work via their type definitions - [ ] `agents resource type show <TYPE>` output matches the actual available CLI flags - [ ] Tests (Behave): scenarios covering dynamic flag generation for at least one built-in and one custom type ## Spec References - Command synopsis: line 311 (`[type-specific-flags...]`) - `resource add` detail: lines 10574–10594 - Resource type `cli_args` definition: lines 23615, 34371–34516 - `cliArg` JSON Schema: lines 34485–34516 - Custom type example with `cli_args`: lines 24341–24402 - Type inheritance with `cli_args`: lines 23636, 23649–23667 - ADR-042: Resource Type Inheritance

Rows
Columns