Merge pull request #914 from opsmill/develop

Merge develop into infrahub-develop

Author: ajtmccarty

.specify/scripts/bash/common.sh

@@ -28,7 +28,7 @@ get_current_branch() {
 
     # For non-git repos, try to find the latest feature directory
     local repo_root=$(get_repo_root)
-    local specs_dir="$repo_root/specs"
+    local specs_dir="$repo_root/dev/specs"
 
     if [[ -d "$specs_dir" ]]; then
         local latest_feature=""
@@ -81,14 +81,14 @@ check_feature_branch() {
     return 0
 }
 
-get_feature_dir() { echo "$1/specs/$2"; }
+get_feature_dir() { echo "$1/dev/specs/$2"; }
 
 # Find feature directory by numeric prefix instead of exact branch match
 # This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
 find_feature_dir_by_prefix() {
     local repo_root="$1"
     local branch_name="$2"
-    local specs_dir="$repo_root/specs"
+    local specs_dir="$repo_root/dev/specs"
 
     # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
     if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
@@ -99,7 +99,7 @@ find_feature_dir_by_prefix() {
 
     local prefix="${BASH_REMATCH[1]}"
 
-    # Search for directories in specs/ that start with this prefix
+    # Search for directories in dev/specs/ that start with this prefix
     local matches=()
     if [[ -d "$specs_dir" ]]; then
         for dir in "$specs_dir"/"$prefix"-*; do

.specify/templates/plan-template.md

@@ -1,7 +1,7 @@
 # Implementation Plan: [FEATURE]
 
 **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
-**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+**Input**: Feature specification from `/dev/specs/[###-feature-name]/spec.md`
 
 **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
 
@@ -38,7 +38,7 @@
 ### Documentation (this feature)
 
 ```text
-specs/[###-feature]/
+dev/specs/[###-feature]/
 ├── plan.md              # This file (/speckit.plan command output)
 ├── research.md          # Phase 0 output (/speckit.plan command)
 ├── data-model.md        # Phase 1 output (/speckit.plan command)

.specify/templates/tasks-template.md

@@ -5,7 +5,7 @@ description: "Task list template for feature implementation"
 
 # Tasks: [FEATURE NAME]
 
-**Input**: Design documents from `/specs/[###-feature-name]/`
+**Input**: Design documents from `/dev/specs/[###-feature-name]/`
 **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
 
 **Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.

.vale/styles/spelling-exceptions.txt

@@ -133,6 +133,7 @@ validators
 Version Control
 Vitest
 VLANs
+yaml
 Yaml
 yamllint
 YouTube

dev/commands/speckit.specify.md

@@ -47,7 +47,7 @@ Given that feature description, do this:
    b. Find the highest feature number across all sources for the short-name:
       - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
       - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
-      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+      - Specs directories: Check for directories matching `dev/specs/[0-9]+-<short-name>`
 
    c. Determine the next available number:
       - Extract all numbers from all three sources

dev/specs/001-end-user-cli/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: End-User CLI (`infrahubctl` command)
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass validation. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
+- Assumptions section documents reasonable defaults for unspecified details.
+- CLI command examples in acceptance scenarios use generic syntax (not framework-specific).

dev/specs/001-end-user-cli/contracts/cli-commands.md

@@ -0,0 +1,64 @@
+# CLI Command Contracts
+
+## Global Options
+
+All commands accept:
+
+- `--branch TEXT` — Target Infrahub branch (default: from config)
+- `--config-file PATH` — Configuration file path (default: infrahubctl.toml)
+- `--output [table|json|csv|yaml]` — Output format (default: table if TTY, json if piped)
+
+## `infrahubctl get <kind> [identifier]`
+
+**List mode** (no identifier):
+
+- Input: kind (positional), --filter (repeatable), --limit INT, --offset INT
+- Output: Table with columns for each attribute + relationship (display names)
+- Exit 0: results found | Exit 80: no results (empty list) | Exit 1: invalid kind
+
+**Detail mode** (with identifier):
+
+- Input: kind (positional), identifier (positional — UUID or display name)
+- Output: Key-value display of all attributes, relationships, metadata
+- Exit 0: found | Exit 1: not found
+
+**Filters**: `--filter name__value="spine01"` (repeatable)
+
+## `infrahubctl create <kind>`
+
+- Input: kind (positional), --set key=value (repeatable), --file PATH
+- --set and --file are mutually exclusive
+- Output: Confirmation with created object ID and display label
+- Exit 0: created | Exit 1: validation error | Exit 1: server error
+
+**File input**: JSON or YAML in Infrahub Object format
+(`apiVersion: infrahub.app/v1`)
+
+## `infrahubctl update <kind> <identifier>`
+
+- Input: kind (positional), identifier (positional), --set key=value
+  (repeatable), --file PATH
+- --set and --file are mutually exclusive
+- Output: Confirmation with old → new values for changed fields
+- Exit 0: updated | Exit 1: not found | Exit 1: validation error
+
+## `infrahubctl delete <kind> <identifier>`
+
+- Input: kind (positional), identifier (positional), --yes (skip confirmation)
+- Output: Confirmation prompt (unless --yes), then success message
+- Exit 0: deleted | Exit 1: not found | Exit 1: dependency conflict
+
+## `infrahubctl schema list`
+
+- Input: --filter TEXT (substring match on kind name)
+- Output: Table with columns: Namespace, Name, Kind, Description
+- Exit 0: always (empty table if no matches)
+
+## `infrahubctl schema show <kind>`
+
+- Input: kind (positional)
+- Output: Formatted display of:
+  - Kind metadata (namespace, label, description, display_labels, HFID)
+  - Attributes table (name, type, required, default, description)
+  - Relationships table (name, peer kind, cardinality, optional)
+- Exit 0: found | Exit 1: invalid kind

dev/specs/001-end-user-cli/data-model.md

@@ -0,0 +1,62 @@
+# Data Model: End-User CLI
+
+This feature does not introduce new persistent data entities. It operates on
+Infrahub's existing data model (Kinds, Nodes, Attributes, Relationships) via
+the SDK client.
+
+The CLI introduces transient structures for formatting and serialization:
+
+## Output Format Envelope
+
+Used when serializing query results to YAML output format.
+
+**Fields**:
+
+- `apiVersion` (str): Always `"infrahub.app/v1"`
+- `kind` (str): Always `"Object"`
+- `spec.kind` (str): The Infrahub Kind being exported (e.g., `"InfraDevice"`)
+- `spec.data` (list[dict]): Array of serialized node objects
+
+Each node in `spec.data` contains:
+
+- Attribute fields as `key: value` pairs
+- Relationship fields as `key: display_name` (single) or
+  `key: {data: [list]}` (many)
+
+This structure matches the existing `InfrahubObjectFileData` model in
+`infrahub_sdk/spec/object.py` and is round-trippable with `ObjectFile`.
+
+## Set Flag Parser
+
+Parses `--set key=value` arguments into a dict suitable for SDK calls.
+
+**Input**: List of `"key=value"` strings from CLI
+**Output**: `dict[str, str | list[str]]`
+
+Validation rules:
+
+- Key MUST exist as an attribute or relationship name in the target Kind's schema
+- Value is a string; the SDK handles type coercion
+- For relationships (cardinality ONE), value is the HFID or UUID of the target node (e.g., `--set site=DC1`)
+- For relationships (cardinality MANY), value is a JSON array of HFID arrays (e.g., `--set tags=[["blue"], ["red"]]`). Each inner array is an HFID supporting multi-component keys (e.g., `[["Cisco", "NX-OS"]]`). The parser detects `[...]` and parses as JSON.
+
+**Relationship resolution**: The CLI passes relationship values through to the
+SDK as HFID references. The SDK/server is responsible for resolving HFIDs to
+internal IDs. The CLI MUST NOT perform its own lookup round-trips.
+
+**SDK dependencies**:
+
+- [opsmill/infrahub-sdk-python#267](https://github.com/opsmill/infrahub-sdk-python/issues/267) — `rebuild_hfid_from_data()`: reconstruct HFID from flat user data based on schema definition
+- [opsmill/infrahub-sdk-python#272](https://github.com/opsmill/infrahub-sdk-python/issues/272) — `node.update(data)`: update attributes and relationships from a dict (eliminates manual per-field mutation)
+
+## Filter Parser
+
+Parses `--filter key=value` arguments into kwargs for `client.filters()`.
+
+**Input**: List of `"attribute__value=x"` strings from CLI
+**Output**: `dict[str, Any]` passed as `**kwargs`
+
+Validation rules:
+
+- Key MUST follow the `attribute__value` or `relationship__id` pattern
+- Invalid keys produce a validation error with available field names