Fix publish/setup docs and Node Oryx TypeScript deploy behavior#318
Conversation
|
@ITSpecialist111 please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
There was a problem hiding this comment.
Pull request overview
Updates the Agent365 CLI and docs to reduce friction when publishing/deploying Node.js/TypeScript agents, with a focus on avoiding common Oryx remote-build failures and clarifying the intended publish workflow.
Changes:
- Adjust Node Oryx manifest generation to skip remote build actions when
dist/is already present in the publish output. - Update guided setup and publish instructions to reflect the current manual-upload workflow and preview discovery behavior.
- Refine App Service Plan SKU guidance to steer users away from F1 for Node.js/TypeScript remote builds.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| src/Microsoft.Agents.A365.DevTools.Cli/Services/NodeBuilder.cs | Detects dist/ in publish output and changes Oryx manifest build behavior/logging accordingly. |
| src/Microsoft.Agents.A365.DevTools.Cli/Services/ConfigurationWizardService.cs | Updates SKU guidance messaging shown in the interactive configuration wizard. |
| src/Microsoft.Agents.A365.DevTools.Cli/Exceptions/NodeBuildFailedException.cs | Expands mitigation steps for Node build failures (notably TypeScript-related guidance). |
| docs/agent365-guided-setup/a365-setup-instructions.md | Clarifies publish workflow (manual upload), adds admin-consent warning, and updates agent discovery guidance during preview. |
| _logger.LogInformation("dist/ folder found in publish output; skipping Oryx remote build " + | ||
| "(TypeScript already compiled locally — avoids tsc-not-found on Azure)."); |
| Console.WriteLine("NOTE: B1 (Basic) is the recommended default. It handles the Node.js/TypeScript"); | ||
| Console.WriteLine(" Oryx remote build (npm install + tsc) within the startup timeout."); | ||
| Console.WriteLine(" F1 (Free) has a 230s cold-start limit that is routinely exceeded by"); | ||
| Console.WriteLine(" TypeScript agent projects during remote build — avoid F1 for Node.js/TS."); | ||
| Console.WriteLine(" B1 may have zero quota in new subscriptions — if creation fails, request"); | ||
| Console.WriteLine(" a quota increase or try a different Azure region."); |
| "If the error is 'tsc: not found' or similar, move 'typescript' from 'devDependencies' to " + | ||
| "'dependencies' in package.json. Azure App Service Oryx runs 'npm install --production' " + | ||
| "which skips devDependencies, so build tools like tsc must be in dependencies.", | ||
| "If the build depends on environment variables or private packages, ensure those are configured on the machine running 'a365 deploy'.", |
| > ⚠️ **WARNING — Do NOT use "Grant admin consent" in the Entra portal for this app registration.** The `AgentIdentityBlueprint.*` permissions above are beta-only and are not visible in the Entra admin center UI. If a Global Admin clicks "Grant admin consent" in the portal after these permissions have been granted via Graph API, the portal's consent mechanism will **silently delete** the `AgentIdentityBlueprint.*` grants. All permission grants for this app must be managed exclusively via the Graph API `appRoleAssignments` endpoint. If the permissions are accidentally removed, re-run the Graph API grants to restore them. | ||
|
|
||
| If the app does not exist, permissions are missing, or admin consent has not been granted, see "What to do if validation fails" below. | ||
|
|
||
| **If validation fails** (app not found, permissions missing, or no admin consent): |
Fix publish/setup docs and Node Oryx TypeScript deploy behavior
Summary of changes:
Clarified publish workflow and setup instructions in documentation.
Added warnings and guidance for Entra admin consent and Copilot/Teams agent discovery.
Updated SKU recommendation logic to prefer B1 and warn against F1 for Node.js/TypeScript agents.
Improved Node.js/TypeScript deployment: Oryx now skips remote build if dist/ exists, preventing tsc-not-found errors.
Enhanced error messages with mitigation steps for TypeScript build issues.
Why these changes?
These updates address common setup and deployment issues, improve onboarding clarity, and reduce friction for new users deploying Node.js/TypeScript agents.