Cross-platform testing for KB source resolution (Linux/macOS)

[rucka]

Context

Follow-up from PR #133 (Story #92) code review. Cross-platform testing was deferred from the story DoD and should be completed before the next npm release.

Problem

The flexible KB source resolution feature (install/update from URLs, local ZIPs, local directories) has not been tested on Linux and macOS. Platform-specific issues may exist:

• Path resolution differences (Windows \ vs Unix /)
• Symlink behavior differences
• File permissions issues
• Shell script compatibility (smoke-tests/)

Tasks

Manual Testing

• Linux testing (Ubuntu 22.04+ or equivalent)

  • Install from local directory (absolute path)
  • Install from local directory (relative path)
  • Install from local ZIP
  • Install with --offline + local source
  • Update from local directory
  • Error scenarios (non-existent path, invalid KB structure)
  • Smoke tests (pnpm smoke-tests)

• macOS testing (macOS 12+)

  • Same test matrix as Linux above

Issues Found

Document any platform-specific issues discovered during testing:

• Path resolution bugs
• Symlink creation failures
• Permission errors
• Shell script incompatibilities

Fixes (if needed)

• Fix platform-specific bugs
• Add platform guards if necessary
• Update tests to cover platform differences

Acceptance Criteria

• All install scenarios work on Linux (Ubuntu 22.04+)
• All install scenarios work on macOS (macOS 12+)
• Smoke tests pass on both platforms
• Platform-specific issues documented or fixed
• Pre-release checklist updated with platform testing steps

Priority

Medium - Should be done before next npm release to ensure CLI works correctly on all supported platforms.

Related

• PR [#92] feat: flexible KB source resolution #133 (story Flexible KB Source Resolution #92 implementation)
• Epic Simple KB Distribution & Installation #65 (Enhanced CLI Packaging & Distribution)
• Story Flexible KB Source Resolution #92 DoD (cross-platform testing deferred)