Add canonical site URL to deploy JSON output

[Copilot]

Problem

The netlify deploy --json command inconsistently returned URL information, making it difficult for scripts and automation to reliably access both the canonical site URL and per-deploy URL:

• Only the per-deploy URL was consistently available via deploy_url
• The canonical site URL was only available via the url field for production deploys
• No documentation explained the semantics of each URL field

Solution

This PR adds a new site_url field that is always present in the JSON output, representing the canonical/primary site URL that remains consistent across all deploys.

JSON Output Changes

Before:

{ "deploy_url": "https://abc123--example.netlify.app", "url": "..." // Only present for production deploys }

After:

{ "site_url": "https://example.netlify.app", // NEW: Always present "deploy_url": "https://abc123--example.netlify.app", // Always present "url": "https://example.netlify.app" // Production only (backward compat) }

Changes

1. Added site_url field to JsonData interface - The canonical/primary site URL (e.g., https://example.netlify.app) that remains consistent across deploys
2. Updated printResults function - Now includes site_url in all JSON outputs, regardless of deployment type
3. Added comprehensive JSDoc documentation - Each JSON field now has clear documentation explaining its purpose and when it's present
4. Added integration tests - New test validates both URLs are present and correctly formatted for draft and production deploys
5. Updated existing test validation - All deploy validation now checks for site_url presence

Field Definitions

• site_url: Primary/canonical URL for the site. Remains consistent across deploys. Always present.
• deploy_url: Unique per-deploy URL. Can be used to preview this specific deploy even after subsequent deploys. Always present.
• url: (Deprecated) Legacy field, same as site_url. Only present for production deploys for backward compatibility.

Benefits

✅ Consistent: Both URLs are now always available in JSON output
✅ Clear: Field names explicitly indicate their purpose
✅ Documented: Comprehensive JSDoc comments explain each field
✅ Backward Compatible: Legacy url field preserved for production deploys
✅ Reliable: Scripts can now consistently access the canonical site URL

Breaking Changes

None. This is a backward-compatible enhancement that only adds a new field. The existing deploy_url field and legacy url field (for production deploys) remain unchanged.

Testing

• Added new integration test: should include both site_url and deploy_url in JSON output
• Validates both URLs are present for draft and production deploys
• Verifies URL format correctness
• Confirms site_url and deploy_url differ for draft deployments
• Ensures backward compatibility with legacy url field
• CodeQL security scan passed with 0 alerts

Original prompt

Deploy CLI outputs (permalink vs deploy URL)

Limitation: netlify deploy --json consistently returns the per‑deploy URL (e.g. https://<id>--<site>.netlify.app) but not a stable permalink/primary domain URL. The url field is inconsistent and not documented as canonical. Suggestion: Always include canonical site/permalink URLs in the JSON result, and document the fields clearly (e.g. primary_url, alias_url). 

---

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.