Skip to content
45 changes: 34 additions & 11 deletions .github/agents/new-item-type.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Use this table to determine which steps apply to the new item type before readin

### Simple Item (no definition, no params)

Only needs Steps 1-3, 9 (add to the standard multi-case match), and 11 (ALL_ITEM_TYPES + basic_item_parametrize).
Only needs Steps 1-3, 9 (add to the standard multi-case match), 10a (review `command_support.yaml` for `unsupported_items`), 11 (ALL_ITEM_TYPES + basic_item_parametrize), 12, and 13.

**Examples:** `Dashboard`, `Datamart`

Expand All @@ -72,19 +72,19 @@ Needs Steps 1-4, 9, 10 (export + import + cp + mv), 11 (ALL_ITEM_TYPES + basic_i

### Item with Creation Parameters

Needs Steps 1-3, 7-9, 11 (ALL_ITEM_TYPES but NOT basic_item_parametrize), 12, and 13.
Needs Steps 1-3, 7-9, 10, 11 (ALL_ITEM_TYPES but NOT basic_item_parametrize), 12, and 13.

**Examples:** `Lakehouse` (enableSchemas), `Warehouse` (enableCaseInsensitive), `KQLDatabase` (dbType, eventhouseId)

### Item with OneLake Folders

Needs Steps 1-3, 5, 9, 11, 12, and 13.
Needs Steps 1-3, 5, 9, 10, 11, 12, and 13.

**Examples:** `Lakehouse` (Files, Tables), `Warehouse` (Files, Tables), `KQLDatabase` (Tables, Shortcut)

### Item with Job Support

Needs Steps 1-3, 6, 9, 11, 12, and 13.
Needs Steps 1-3, 6, 9, 10, 11, 12, and 13.

**Examples:** `Notebook` (RunNotebook), `DataPipeline` (Pipeline), `SparkJobDefinition` (sparkjob)

Expand Down Expand Up @@ -324,10 +324,28 @@ case ItemType.NEW_ITEM:

This file controls which CLI commands are enabled for each item type. Add the new item type's snake_case name to the appropriate command sections based on the API Support Matrix from the Prerequisites.

**Always add to these sections** (basic item support):
- No changes needed for `ls`, `cd`, `exists`, `get`, `set`, `rm`, `open`, `mkdir` -- these work for all item types via the generic items API.
> **This step applies to ALL item types, not just items with definition support.** Sub-step 10a (`unsupported_items` review) always applies. Sub-steps 10b-10e apply only to items with definition support.

#### 10a. Check `unsupported_items` lists (always)

Review the `unsupported_items` sections for `rm`, `get`, `set`, and `mkdir`. If the new item type does **not** support one of these operations via the Fabric REST API, add it to the relevant `unsupported_items` list. Check existing entries (e.g., `dashboard`, `paginated_report`) for reference.

> **Ask the requestor:** "Can this item type be deleted (rm), read with detailed properties (get), updated (set), and created (mkdir) via the standard items API?" Add the item to `unsupported_items` for any command it does not support.

```yaml
# Example: item cannot be deleted or created via API
rm:
unsupported_items:
# ... existing items ...
- new_item # <-- Add here if rm is NOT supported
mkdir:
unsupported_items:
# ... existing items ...
- new_item # <-- Add here if mkdir is NOT supported
```

#### 10b. Add to `export` (if the item supports `getItemDefinition` API)

**Add to `export` if the item supports `getItemDefinition` API:**
```yaml
commands:
fs:
Expand All @@ -338,23 +356,26 @@ commands:
- new_item # <-- Add here, maintain alphabetical order
```

**Add to `import` if the item supports `createItem` with definition:**
#### 10c. Add to `import` (if the item supports `createItem` with definition)

```yaml
import:
supported_items:
# ... existing items ...
- new_item # <-- Add here
```

**Add to `mv` if the item supports all three definition APIs:**
#### 10d. Add to `mv` (if the item supports all three definition APIs)

```yaml
mv:
supported_items:
# ... existing items ...
- new_item # <-- Add here
```

**Add to `cp` if the item supports all three definition APIs:**
#### 10e. Add to `cp` (if the item supports all three definition APIs)

```yaml
cp:
supported_items:
Expand All @@ -375,6 +396,8 @@ commands:

Add the new item type to the parametrized test lists so that existing tests automatically cover the new item type.

> **IMPORTANT: Do NOT create VCR cassette recording files.** Only modify the parametrization lists in `conftest.py`. The recording files under `tests/test_commands/recordings/` are generated separately by running the tests against a live environment and should never be hand-crafted or generated by this agent.

#### 11a. Add to `ALL_ITEM_TYPES`

This list drives the comprehensive test suite (cd, ls, exists, rm, get, set, mkdir).
Expand Down Expand Up @@ -553,7 +576,7 @@ After completing all applicable steps, run these commands to verify each integra
| 7. Creation params | `grep -n 'ItemType.NEW_ITEM' src/fabric_cli/utils/fab_cmd_mkdir_utils.py \| grep -i param` | Has creation params |
| 8. Creation payload | `grep -n 'ItemType.NEW_ITEM' src/fabric_cli/utils/fab_cmd_mkdir_utils.py \| grep -i payload` | Has creation payload |
| 9. Import payload | `grep -n 'ItemType.NEW_ITEM' src/fabric_cli/core/hiearchy/fab_item.py` | Always |
| 10. Command support | `grep -n 'new_item' src/fabric_cli/core/fab_config/command_support.yaml` | Has definitions |
| 10. Command support | `grep -n 'new_item' src/fabric_cli/core/fab_config/command_support.yaml` | Always (check both supported_items and unsupported_items) |
| 11a. ALL_ITEM_TYPES | `grep -n 'NEW_ITEM' tests/test_commands/conftest.py \| grep -i all_item` | Always |
| 11b. basic_item | `grep -n 'NEW_ITEM' tests/test_commands/conftest.py \| grep -i basic` | Basic items only |
| 11c. mv params | `grep -n 'NEW_ITEM' tests/test_commands/conftest.py \| grep -i mv` | Has mv support |
Expand Down
Loading