Summary

Improve error messages in apm install to be more actionable and helpful, especially for users new to APM or working in brownfield projects.

Current Behavior

$ apm install
Error: No apm.yml found. Run 'apm init' first.

Problems:

• Terse, unhelpful
• Only suggests one path forward
• Doesn't explain what apm init does
• Missing the new auto-bootstrap capability

Target Behavior

Scenario 1: No apm.yml, no packages

$ apm install
❌ No apm.yml found

💡 To get started:
   • apm init              - Create minimal apm.yml
   • apm install <org/repo> - Auto-create apm.yml + install package
   
   Example: apm install danielmeppiel/design-guidelines

Scenario 2: No packages found in apm.yml

$ apm install
⚠️  No dependencies found in apm.yml

💡 Add dependencies:
   • apm install <org/repo>  - Add APM package
   • Edit apm.yml manually    - Add dependencies section

Implementation Requirements

Error Message Guidelines

• Clear problem statement - What went wrong
• Actionable next steps - What user can do now
• Concrete examples - Show actual commands they can copy
• Helpful context - Why they might want each option

Code Changes

# In install command
if not Path('apm.yml').exists():
    if not packages:
        _rich_error("No apm.yml found")
        _rich_blank_line()
        _rich_info("💡 To get started:")
        _rich_info("   • apm init              - Create minimal apm.yml")
        _rich_info("   • apm install <org/repo> - Auto-create apm.yml + install package")
        _rich_blank_line()
        _rich_info("   Example: apm install danielmeppiel/design-guidelines")
        sys.exit(1)

Additional Error Improvements

• Package validation errors - Show what format is expected
• Network errors - Suggest checking connectivity
• Permission errors - Explain token requirements
• Dependency conflicts - Show what's conflicting and why

Acceptance Criteria

• Error when no apm.yml and no packages shows both init options
• Error message includes concrete example command
• Empty dependencies in apm.yml shows helpful suggestion
• Package format errors explain expected format (org/repo)
• All error messages follow consistent style (problem → solutions → example)
• Error messages use Rich formatting for better readability
• Tests verify error message content

Related

• Depends on issue Add auto-bootstrap in apm install when no apm.yml exists #14 (auto-bootstrap) for accurate messaging
• Part of npm-parity redesign for brownfield adoption