feat: generalize $ref resolver + shared $ref-aware azure.yaml edit helper

[huimiu]

Part of #8775 · Design spec PR #8590 (docs/specs/unify-azure-yaml/spec.md §2.4).

Base branch is huimiu/foundry-azure-yaml (the Foundry azure.yaml integration branch). This PR is intentionally independent of #8675.

What

PR3 of the "unify Foundry config in azure.yaml" follow-up.

Resolver generalization (includes.go — docs + tests only)

The $ref resolver from #8627 already resolves $ref at any map/sequence node, so the separate-services shapes need no new resolution logic — only a generalized documented contract and coverage:

• Service-entry-level $ref (top-level inline map, beside host: / the service key, which core strips).
• Deployment array-item $ref on the project service.
• Per-file rebasing of project / instructions / nested $ref (already implemented).

Shared $ref-aware YAML edit helper (includes_edit.go — new)

A comment-preserving writer that the #8049 composition commands also use, so reads and writes of $ref entries agree:

• YAMLDocument load / parse / save / bytes — braydonk round-trip with two-space indent and block-scalar style, matching how azd core writes azure.yaml.
• ServiceEntry(name, create), EntryRef(entry), SetServiceField(name, key, value, EditTarget).
• EditInline overlays a key beside $ref (the §2.4 default); EditRefFile follows the $ref into the split file (path resolved with the resolver's shared logic), falling back to inline when the entry is not $ref-backed.
• Reuses core pkg/yamlnode for node ops and the resolver's refKey / refTargetPath, so the writer and resolver agree on what a $ref entry is and where it points.

Out of scope

Wiring the resolver into each provider's parse path (rides with PR2), remote URL $ref fetching, and JSON-Schema validation of loaded entries. No azd-core changes; no dependency on #8675.

Tests

go test ./internal/project/...

• Resolver shapes: service-entry top-level $ref (+ overlay), project deployments: array-item $ref (+ inline item, + overlay).
• Edit helper: round-trip comment/order preservation, find / create / missing, $ref detection, inline overlay + read-back agreement via ResolveFileRefs, in-place update (comment preserved), EditRefFile split-file write, non-$ref fallback, and missing ref-file error.

gofmt -s, golangci-lint, and cspell are clean.

[Copilot]

Pull request overview

This PR extends the existing $ref include resolver contract to explicitly cover the “separate-services” azure.yaml shape, and adds a shared $ref-aware, comment-preserving YAML edit helper so read/write behavior stays consistent across Foundry-related commands and extensions.

Changes:

• Document the generalized ResolveFileRefs contract to cover service-entry top-level $ref, deployments array-item $ref, and nested $ref recursion.
• Add resolver test coverage for the new documented shapes (including shallow sibling overlay behavior).
• Introduce includes_edit.go (YAMLDocument) for comment/order-preserving edits, with $ref-aware inline-vs-ref-file targeting and corresponding tests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
cli/azd/extensions/azure.ai.agents/internal/project/includes.go	Updates resolver documentation to describe separate-services $ref shapes and contract.
cli/azd/extensions/azure.ai.agents/internal/project/includes_test.go	Adds tests for service-entry-level and deployments array-item $ref resolution + overlays.
cli/azd/extensions/azure.ai.agents/internal/project/includes_edit.go	Adds a $ref-aware YAML editing helper that preserves comments/key order and can write inline or into split files.
cli/azd/extensions/azure.ai.agents/internal/project/includes_edit_test.go	Adds tests for round-trip stability and for inline/ref-file edit behavior aligning with ResolveFileRefs.