Enhance auth0_save_credentials_to_file with framework aware credential writing

[wdaimee]

Changes

This change introduces framework aware credentials writing and a comment-and-append strategy for the auth0_save_credentials_to_file tool. Rather than appending credentials to a .env file (which could result in duplicate keys), the tool now comments out any existing lines whose keys conflict with the incoming credentials, preservers all other content (comments, blank lines, unrelated variables), and appends the new credentials at the end.

The tool now leverages Auth0's CDN hosted quickstart specifications to determine the correct environment variable names, target filenames, and required keys, for each supported framework (React, Vue, Angular, Next.js). This means a Next.js project gets AUTH0_SECRET, AUTH0_ISSUER_BASE_URL, and AUTH0_BASE_URL written to .env.local, while a React SPA gets only public keys written to .env.local.

When a framework's quickstart spec is unavailable on the CDN (unsupported frameworks or CDN error), the tool falls back to the original hardcoded Auth0 variables (AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_CALLBACK_URL), ensuring no regression for unsupported frameworks.

The following changes have been implemented:

Added the following new utilities:

1. src/utils/env-credentials.ts - Orchestrator for credential resolution and writing (spec-driven and fallback paths)
2. src/utils/quickstarts.ts - CDN spec fetcher with caching and Zod validation
3. src/utils/onboarding.ts - Callback URL resolution helper and framework detection
4. src/utils/fetch.ts - Shared fetch wrapper with retry support

Updates to the following files:

1. src/utils/credentials-writer.ts - Comment-and-append logic replacing simple append; added parseEnv() and commentOutConflictingKeys()
2. src/tools/applications.ts - Updated tool schema (file_path -> framework + project_path) and handler delegation to resolveAndWriteCredentials()
3. src/tools/analytics.ts - Added trackCredentialResolution() method tracking framework, resolution path (spec vs fallback), secret generation, and sorted keys written.

Packages Added:

1. Zod for defining and validating schema

References

Please include relevant links supporting this change such as a:

https://auth0team.atlassian.net/browse/DXAA-553
https://auth0team.atlassian.net/browse/DXAA-554

Testing

Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.

Tool tested with multiple frameworks:

1. React project (supported):

2. Next.js project (supported):

4. Svelte (unsupported framework)

5. Comment-and-append logic:

E2E Tests in API2 Pass for mcp-api:

These changes can be tested by:

1. Switch to the feat/DXAA-auth0-save-credentials-to-file-onboarding-updates branch
2. Run npm run build
3. Initialize the MCP server: npx . init --client vscode (or your preferred client)
4. Ensure the MCP server is running
5. Create an application using auth0_create_application
6. Call auth0_save_credentials_to_file with framework, e.g.: "nextjs", project_path: "/path/to/your/nextjs/project", and the client_id from step 5
7. Verify the .env.local file is created in the project directory with framework-specific variable names (e.g., AUTH0_SECRET, AUTH0_ISSUER_BASE_URL)
8. Repeat with another supported framework: "react" — verify no client_secret is written (SPA) and the correct env filename is used
9. Test with an unsupported framework (e.g., framework: "flask") — verify fallback to hardcoded AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET in .env.local

• This change adds unit test coverage
• This change adds integration test coverage

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors

[wdaimee]

ProdSec PostImp Review Requested: https://auth0team.atlassian.net/browse/PSREV-2889

[nicogarcia]

LGTM 🚀