feat(embedder): interactive install prompt for @huggingface/transformers

[carlos-alm]

Summary

• Move @huggingface/transformers from optionalDependencies to peerDependencies (with optional: true meta) so npm no longer auto-installs it for every user
• Add interactive promptInstall() helper in src/embedder.js that prompts users to install the package when they run embed/search without it
• Non-TTY environments (CI, piped stdin) skip the prompt and print the existing error message + exit

Test plan

• npm test — all existing tests pass (they mock @huggingface/transformers)
• Manual: uninstall @huggingface/transformers, run node src/cli.js search "test", verify prompt appears, answer "y", verify install + retry works
• Manual: pipe stdin (echo "" | node src/cli.js search "test") — verify it skips prompt and prints error

[claude]

Claude finished @carlos-alm's task —— View job

---

Code Review Complete

Todo List

• Read changed files to understand implementation
• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity
• Phase 4: Code Quality Review
• Provide final assessment and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: The current setup has @huggingface/transformers as an optionalDependency, which means npm automatically installs it for every user even when they don't need semantic search functionality. This wastes bandwidth and disk space for users who only want basic dependency graph features.

Why This Approach: Moving to peerDependencies with optional: true prevents automatic installation while still allowing the package to be resolved when present. The interactive prompt provides a user-friendly way to install only when needed.

Risk Assessment: This is a legitimate optimization that addresses a real user experience issue. The approach is technically sound and follows npm best practices.

Phase 2: Configuration Change Detection ✅

Dependency Changes Reviewed:

• JUSTIFIED: Moving @huggingface/transformers from optionalDependencies to peerDependencies with optional: true meta
• PURPOSE: Prevents automatic installation while preserving optional resolution
• RISK: LOW - This is a standard npm pattern for optional peer dependencies

No concerning configuration relaxation detected. The dependency change serves a legitimate user experience improvement.

Phase 3: Test Integrity ✅

Test Coverage Analysis:

• No test files were modified ✅
• No test assertions weakened ✅
• No test timeouts increased ✅
• Existing tests mock @huggingface/transformers so they should continue working ✅
• Test plan includes manual verification of the interactive prompt behavior ✅

The PR maintains test integrity and provides clear manual testing steps for the new functionality.

Phase 4: Code Quality Review ✅

Security Analysis:

• promptInstall() properly uses execFileSync() instead of exec() to prevent command injection (lines 241-244) ✅
• Uses exact package name @huggingface/transformers without user input interpolation ✅
• Timeout set to 5 minutes (300_000ms) prevents indefinite hanging ✅

Implementation Quality:

• TTY detection (process.stdin.isTTY) properly handles CI/automated environments (line 233) ✅
• Error handling: catches import failures and install failures gracefully (lines 261, 246, 267) ✅
• User experience: clear prompts, uses stderr for interactive output (line 236) ✅
• Consistent with existing codebase patterns and error handling ✅

Minor Considerations:

• The prompt uses [y/N] convention with lowercase 'y' requiring exact match - this is standard and appropriate
• Install failure handling is graceful - attempts to import after install, falls back to error message if that fails
• Non-TTY behavior preserves existing error message format for backward compatibility

Final Assessment

Root Cause Analysis

Problem Being Solved: Eliminating unnecessary installation of the ~150MB @huggingface/transformers package for users who don't need semantic search, improving installation speed and reducing disk usage.

Why This Approach: Standard npm pattern using peerDependencies with optional metadata, combined with user-friendly interactive installation when actually needed.

Risk Assessment: LOW - Well-implemented solution following established patterns with proper security practices.

Critical Concerns

None identified. This is a clean implementation that improves user experience without introducing risks.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Solid implementation solving a real user problem. Proper security practices, good error handling, maintains backward compatibility. The interactive prompt is well-designed and the dependency management approach follows npm best practices. Only minor consideration is that this changes the installation behavior, but that's the intended improvement.

---

[greptile-apps]

Greptile Summary

Improved package installation experience by moving @huggingface/transformers to peerDependencies with optional metadata, preventing automatic installation for all users. When users run embed or search commands without the package, they now receive an interactive prompt offering to install it (with proper TTY detection to skip prompts in CI/non-interactive environments).

Key improvements:

• Reduced installation size for users who don't need semantic search features
• Interactive install prompt with clear user confirmation
• Secure command execution using execFileSync with array arguments (no shell injection risk)
• Proper handling of non-TTY environments (CI, piped stdin) - skips prompt and shows manual install instructions
• Graceful error handling if installation succeeds but package fails to load

Testing notes:

• Existing tests continue to work (they mock @huggingface/transformers)
• Manual testing should verify the prompt appears, install works, and non-TTY environments skip the prompt correctly

Confidence Score: 5/5

• This PR is safe to merge with no blocking issues
• The implementation is secure (uses execFileSync with array args to prevent command injection), handles all error cases gracefully, and properly detects TTY vs non-TTY environments. The package.json change is correct (peerDependencies with optional meta), and existing tests will continue to work since they mock the transformers package.
• No files require special attention

Important Files Changed

Filename	Overview
package.json	moved @huggingface/transformers from optionalDependencies to peerDependencies with optional meta, preventing auto-install while preserving the relationship
src/embedder.js	added interactive install prompt with proper TTY detection, secure command execution, and graceful fallbacks for non-interactive environments

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([User runs embed/search]) --> TryImport{Try import<br/>transformers}
    TryImport -->|Success| UsePackage[Use transformers]
    TryImport -->|Fail| CheckTTY{Is stdin TTY?}
    CheckTTY -->|No| ErrorNonTTY[Print install error<br/>Exit 1]
    CheckTTY -->|Yes| Prompt[Prompt user:<br/>Install now? y/N]
    Prompt --> UserAnswer{User<br/>answers 'y'?}
    UserAnswer -->|No| ErrorDeclined[Print install error<br/>Exit 1]
    UserAnswer -->|Yes| NpmInstall[npm install<br/>timeout: 5min]
    NpmInstall -->|Success| RetryImport{Try import again}
    NpmInstall -->|Fail| ErrorDeclined
    RetryImport -->|Success| UsePackage
    RetryImport -->|Fail| ErrorLoadFail[Print load error<br/>Exit 1]
    UsePackage --> End([Continue execution])

Loading

_{Last reviewed commit: 8e717b2}

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[claude]

Claude finished @carlos-alm's task —— View job

---

Code Review Complete

Todo List

• Read changed files to understand implementation
• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity
• Phase 4: Code Quality Review
• Provide final assessment and recommendation

Phase 1: Root Cause Analysis ✅

Problem Being Solved: The current setup has @huggingface/transformers as an optionalDependency, which means npm automatically installs it for every user even when they don't need semantic search functionality. This wastes bandwidth and disk space for users who only want basic dependency graph features.

Why This Approach: Moving to peerDependencies with optional: true prevents automatic installation while still allowing the package to be resolved when present. The interactive prompt provides a user-friendly way to install only when needed.

Risk Assessment: This is a legitimate optimization that addresses a real user experience issue. The approach is technically sound and follows npm best practices.

Phase 2: Configuration Change Detection ✅

Dependency Changes Reviewed:

• JUSTIFIED: Moving @huggingface/transformers from optionalDependencies to peerDependencies with optional: true meta
• PURPOSE: Prevents automatic installation while preserving optional resolution
• RISK: LOW - This is a standard npm pattern for optional peer dependencies

No concerning configuration relaxation detected. The dependency change serves a legitimate user experience improvement.

Phase 3: Test Integrity ✅

Test Coverage Analysis:

• No test files were modified ✅
• No test assertions weakened ✅
• No test timeouts increased ✅
• Existing tests mock @huggingface/transformers so they should continue working ✅
• Test plan includes manual verification of the interactive prompt behavior ✅

The PR maintains test integrity and provides clear manual testing steps for the new functionality.

Phase 4: Code Quality Review ✅

Security Analysis:

• promptInstall() properly uses execFileSync() instead of exec() to prevent command injection (lines 241-244) ✅
• Uses exact package name @huggingface/transformers without user input interpolation ✅
• Timeout set to 5 minutes (300_000ms) prevents indefinite hanging ✅

Implementation Quality:

• TTY detection (process.stdin.isTTY) properly handles CI/automated environments (line 233) ✅
• Error handling: catches import failures and install failures gracefully (lines 261, 246, 267) ✅
• User experience: clear prompts, uses stderr for interactive output (line 236) ✅
• Consistent with existing codebase patterns and error handling ✅

Minor Considerations:

• The prompt uses [y/N] convention with lowercase 'y' requiring exact match - this is standard and appropriate
• Install failure handling is graceful - attempts to import after install, falls back to error message if that fails
• Non-TTY behavior preserves existing error message format for backward compatibility

Final Assessment

Root Cause Analysis

Problem Being Solved: Eliminating unnecessary installation of the ~150MB @huggingface/transformers package for users who don't need semantic search, improving installation speed and reducing disk usage.

Why This Approach: Standard npm pattern using peerDependencies with optional metadata, combined with user-friendly interactive installation when actually needed.

Risk Assessment: LOW - Well-implemented solution following established patterns with proper security practices.

Critical Concerns

None identified. This is a clean implementation that improves user experience without introducing risks.

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: Solid implementation solving a real user problem. Proper security practices, good error handling, maintains backward compatibility. The interactive prompt is well-designed and the dependency management approach follows npm best practices. Only minor consideration is that this changes the installation behavior, but that's the intended improvement.

---