UX: Extend npm/pip package name validation error messages with naming rules #31721

Problem

When a workflow installs a package with an invalid name, the compiler emits a minimal error:

invalid npm package name: "My Package"

These messages identify the offending value but give no indication of the naming rules, forcing users to consult external documentation (npm docs or PEP 508) before they can fix their workflow.

Proposed Change

File to modify: pkg/workflow/name_validation.go (single file)

Extend the error messages to include the rule summary and a canonical example:

Before (lines 43–46):

return fmt.Errorf("invalid npm package name: %q", pkg)

After:

return fmt.Errorf("invalid npm package name: %q — npm names must be lowercase alphanumeric and may include hyphens, dots, and underscores (e.g. \"my-package\" or \"`@scope/name`\")", pkg)

Before (lines 54–55):

return fmt.Errorf("invalid pip package name: %q", pkgName)

After:

return fmt.Errorf("invalid pip package name: %q — PyPI names must start and end with a letter or digit, with hyphens, underscores, or dots allowed inside (e.g. \"requests\" or \"my-package\")", pkgName)

Why This Matters

• Users can understand and fix the issue from the error message alone
• Aligns with existing error message patterns in the codebase (see mcp_argument_validation.go for the gold standard)
• Reduces time-to-fix for a common workflow authoring mistake

Scope

• Single file: pkg/workflow/name_validation.go
• Update test assertions in pkg/workflow/name_validation_test.go to match new message format
• No other files need to change

Design Principle

Clarity and Precision — error messages should explain the constraint, not just flag the violation.

📊 User experience analysis by Delight · ● 19.6M · ◷

• expires on May 14, 2026, 3:41 PM UTC