@paulduvall/claude-dev-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +88 -37
  3. package/bin/claude-commands +307 -65
  4. package/commands/active/xarchitecture.md +393 -0
  5. package/commands/active/xconfig.md +127 -0
  6. package/commands/active/xcontinue.md +92 -0
  7. package/commands/active/xdebug.md +130 -0
  8. package/commands/active/xdocs.md +178 -0
  9. package/commands/active/xexplore.md +94 -0
  10. package/commands/active/xgit.md +149 -0
  11. package/commands/active/xpipeline.md +152 -0
  12. package/commands/active/xquality.md +96 -0
  13. package/commands/active/xrefactor.md +198 -0
  14. package/commands/active/xrelease.md +142 -0
  15. package/commands/active/xsecurity.md +92 -0
  16. package/commands/active/xspec.md +174 -0
  17. package/commands/active/xtdd.md +151 -0
  18. package/commands/active/xtest.md +89 -0
  19. package/commands/active/xverify.md +80 -0
  20. package/commands/experiments/xact.md +742 -0
  21. package/commands/experiments/xanalytics.md +113 -0
  22. package/commands/experiments/xanalyze.md +70 -0
  23. package/commands/experiments/xapi.md +161 -0
  24. package/commands/experiments/xatomic.md +112 -0
  25. package/commands/experiments/xaws.md +85 -0
  26. package/commands/experiments/xcicd.md +337 -0
  27. package/commands/experiments/xcommit.md +122 -0
  28. package/commands/experiments/xcompliance.md +182 -0
  29. package/commands/experiments/xconstraints.md +89 -0
  30. package/commands/experiments/xcoverage.md +90 -0
  31. package/commands/experiments/xdb.md +102 -0
  32. package/commands/experiments/xdesign.md +121 -0
  33. package/commands/experiments/xdevcontainer.md +238 -0
  34. package/commands/experiments/xevaluate.md +111 -0
  35. package/commands/experiments/xfootnote.md +12 -0
  36. package/commands/experiments/xgenerate.md +117 -0
  37. package/commands/experiments/xgovernance.md +149 -0
  38. package/commands/experiments/xgreen.md +66 -0
  39. package/commands/experiments/xiac.md +118 -0
  40. package/commands/experiments/xincident.md +137 -0
  41. package/commands/experiments/xinfra.md +115 -0
  42. package/commands/experiments/xknowledge.md +115 -0
  43. package/commands/experiments/xmaturity.md +120 -0
  44. package/commands/experiments/xmetrics.md +118 -0
  45. package/commands/experiments/xmonitoring.md +128 -0
  46. package/commands/experiments/xnew.md +903 -0
  47. package/commands/experiments/xobservable.md +114 -0
  48. package/commands/experiments/xoidc.md +165 -0
  49. package/commands/experiments/xoptimize.md +115 -0
  50. package/commands/experiments/xperformance.md +112 -0
  51. package/commands/experiments/xplanning.md +131 -0
  52. package/commands/experiments/xpolicy.md +115 -0
  53. package/commands/experiments/xproduct.md +98 -0
  54. package/commands/experiments/xreadiness.md +75 -0
  55. package/commands/experiments/xred.md +55 -0
  56. package/commands/experiments/xrisk.md +128 -0
  57. package/commands/experiments/xrules.md +124 -0
  58. package/commands/experiments/xsandbox.md +120 -0
  59. package/commands/experiments/xscan.md +102 -0
  60. package/commands/experiments/xsetup.md +123 -0
  61. package/commands/experiments/xtemplate.md +116 -0
  62. package/commands/experiments/xtrace.md +212 -0
  63. package/commands/experiments/xux.md +171 -0
  64. package/commands/experiments/xvalidate.md +104 -0
  65. package/commands/experiments/xworkflow.md +113 -0
  66. package/hooks/.smellrc.example.json +19 -0
  67. package/hooks/README.md +263 -0
  68. package/hooks/check-commit-signing.py +127 -0
  69. package/hooks/check-complexity.py +38 -0
  70. package/hooks/check-security.py +37 -0
  71. package/hooks/claude-wrapper.sh +29 -0
  72. package/hooks/config.py +110 -0
  73. package/hooks/file-logger.sh +100 -0
  74. package/hooks/lib/argument-parser.sh +427 -0
  75. package/hooks/lib/config-constants.sh +230 -0
  76. package/hooks/lib/context-manager.sh +560 -0
  77. package/hooks/lib/error-handler.sh +423 -0
  78. package/hooks/lib/execution-engine.sh +444 -0
  79. package/hooks/lib/execution-results.sh +113 -0
  80. package/hooks/lib/execution-simulation.sh +114 -0
  81. package/hooks/lib/field-validators.sh +104 -0
  82. package/hooks/lib/file-utils.sh +398 -0
  83. package/hooks/lib/subagent-discovery.sh +468 -0
  84. package/hooks/lib/subagent-validator.sh +407 -0
  85. package/hooks/lib/validation-reporter.sh +134 -0
  86. package/hooks/on-error-debug.sh +226 -0
  87. package/hooks/pre-commit-quality.sh +204 -0
  88. package/hooks/pre-commit-test-runner.sh +132 -0
  89. package/hooks/pre-write-security.sh +115 -0
  90. package/hooks/prevent-credential-exposure.sh +279 -0
  91. package/hooks/security_bandit.py +177 -0
  92. package/hooks/security_checks.py +97 -0
  93. package/hooks/security_secrets.py +81 -0
  94. package/hooks/security_trojan.py +61 -0
  95. package/hooks/settings.example.json +52 -0
  96. package/hooks/smell_checks.py +238 -0
  97. package/hooks/smell_javascript.py +231 -0
  98. package/hooks/smell_python.py +110 -0
  99. package/hooks/smell_ruff.py +70 -0
  100. package/hooks/smell_types.py +72 -0
  101. package/hooks/subagent-trigger-simple.sh +202 -0
  102. package/hooks/subagent-trigger.sh +253 -0
  103. package/hooks/suppression.py +82 -0
  104. package/hooks/tab-color.sh +70 -0
  105. package/hooks/verify-before-edit.sh +135 -0
  106. package/lib/backup-restore-command.js +140 -0
  107. package/lib/base/base-command.js +252 -0
  108. package/lib/base/command-result.js +184 -0
  109. package/lib/config/constants.js +255 -0
  110. package/lib/config.js +48 -6
  111. package/lib/configure-command.js +428 -0
  112. package/lib/dependency-validator.js +64 -5
  113. package/lib/hook-installer-core.js +2 -2
  114. package/lib/installation-instruction-generator.js +213 -495
  115. package/lib/installer.js +134 -56
  116. package/lib/oidc-command.js +740 -0
  117. package/lib/services/backup-list-service.js +226 -0
  118. package/lib/services/backup-service.js +230 -0
  119. package/lib/services/command-installer-service.js +217 -0
  120. package/lib/services/logger-service.js +201 -0
  121. package/lib/services/package-manager-service.js +319 -0
  122. package/lib/services/platform-instruction-service.js +294 -0
  123. package/lib/services/recovery-instruction-service.js +348 -0
  124. package/lib/services/restore-service.js +221 -0
  125. package/lib/setup-command.js +359 -0
  126. package/lib/setup-wizard.js +155 -262
  127. package/lib/uninstall-command.js +100 -0
  128. package/lib/utils/claude-path-config.js +184 -0
  129. package/lib/utils/file-system-utils.js +152 -0
  130. package/lib/utils.js +8 -4
  131. package/lib/verify-command.js +430 -0
  132. package/package.json +7 -3
  133. package/scripts/postinstall.js +172 -157
  134. package/subagents/debug-specialist.md +7 -0
  135. package/templates/README.md +115 -0
  136. package/templates/basic-settings.json +30 -0
  137. package/templates/comprehensive-settings.json +57 -0
  138. package/templates/global-claude.md +344 -0
  139. package/templates/hybrid-hook-config.yaml +132 -0
  140. package/templates/security-focused-settings.json +62 -0
  141. package/templates/subagent-hooks.yaml +188 -0
  142. package/lib/package-manager-service.js +0 -270
  143. package/subagents/debug-context.md +0 -197
@@ -1,55 +1,28 @@
1
1
  /**
2
- * Installation Instruction Generator
2
+ * Installation Instruction Generator (Refactored)
3
3
  *
4
- * Generates platform-specific installation instructions and recovery guidance.
5
- * Extracted from DependencyValidator as part of Phase 1 bloater refactoring.
4
+ * Lightweight orchestrator for generating platform-specific installation instructions and recovery guidance.
5
+ * Refactored to use focused services following Single Responsibility Principle.
6
6
  *
7
7
  * Features:
8
- * - Cross-platform installation instructions
9
- * - Package manager integration
10
- * - Download link management
11
- * - Alternative installation methods
12
- * - Recovery and troubleshooting guidance
8
+ * - Cross-platform installation instructions via PlatformInstructionService
9
+ * - Package manager integration via PackageManagerService
10
+ * - Recovery and troubleshooting guidance via RecoveryInstructionService
13
11
  */
14
12
 
15
- const PackageManagerService = require('./package-manager-service');
16
- const PlatformUtils = require('./platform-utils');
13
+ const PlatformInstructionService = require('./services/platform-instruction-service');
14
+ const PackageManagerService = require('./services/package-manager-service');
15
+ const RecoveryInstructionService = require('./services/recovery-instruction-service');
16
+ const LoggerService = require('./services/logger-service');
17
17
 
18
18
  class InstallationInstructionGenerator {
19
- constructor() {
19
+ constructor(logger = null) {
20
+ this.platformService = new PlatformInstructionService();
20
21
  this.packageManagerService = new PackageManagerService();
21
- this.platformUtils = new PlatformUtils();
22
- this.config = {
23
- downloadLinks: this._createDownloadLinks()
24
- };
22
+ this.recoveryService = new RecoveryInstructionService();
23
+ this.logger = logger || new LoggerService();
25
24
  }
26
-
27
- /**
28
- * Create download links for common tools
29
- * @returns {Object} Download links by tool and platform
30
- * @private
31
- */
32
- _createDownloadLinks() {
33
- return {
34
- git: {
35
- linux: 'https://git-scm.com/download/linux',
36
- darwin: 'https://git-scm.com/download/mac',
37
- win32: 'https://git-scm.com/download/win'
38
- },
39
- node: {
40
- all: 'https://nodejs.org/en/download/'
41
- },
42
- python: {
43
- all: 'https://www.python.org/downloads/'
44
- },
45
- docker: {
46
- linux: 'https://docs.docker.com/engine/install/',
47
- darwin: 'https://docs.docker.com/desktop/install/mac-install/',
48
- win32: 'https://docs.docker.com/desktop/install/windows-install/'
49
- }
50
- };
51
- }
52
-
25
+
53
26
  /**
54
27
  * Generate installation instructions for missing dependency
55
28
  * @param {Object} dependency - Missing dependency
@@ -57,61 +30,78 @@ class InstallationInstructionGenerator {
57
30
  * @returns {Object} Installation instructions
58
31
  */
59
32
  generateInstallationInstructions(dependency, platform = process.platform) {
60
- const context = this._createInstructionContext(dependency, platform);
61
- const instructions = this._initializeInstructions(platform);
62
-
63
- this._addPlatformPackageManagers(instructions, context);
64
- this._setDefaultPackageManager(instructions);
65
- this._handleNpmPackageSpecific(instructions, context);
66
- this._addAlternativeInstallationMethods(instructions, dependency, platform);
33
+ this.logger.debug('Generating installation instructions', {
34
+ dependency: dependency.name,
35
+ platform
36
+ });
37
+
38
+ try {
39
+ // Get platform-specific instructions
40
+ const platformInstructions = this.platformService.generatePlatformInstructions(platform, dependency);
41
+
42
+ // Get package manager instructions
43
+ const packageManagerInstructions = this.packageManagerService.generateInstallationInstructions(
44
+ dependency.packageName || dependency.name,
45
+ {
46
+ global: dependency.global,
47
+ version: dependency.version
48
+ }
49
+ );
50
+
51
+ // Combine instructions
52
+ const instructions = {
53
+ dependency: dependency.name,
54
+ platform,
55
+ packageManagers: packageManagerInstructions,
56
+ downloadLinks: platformInstructions.downloadLinks,
57
+ notes: platformInstructions.notes,
58
+ troubleshooting: platformInstructions.troubleshooting
59
+ };
67
60
 
68
- return instructions;
61
+ this.logger.debug('Generated installation instructions', {
62
+ managersCount: packageManagerInstructions.length,
63
+ notesCount: instructions.notes.length
64
+ });
65
+
66
+ return instructions;
67
+ } catch (error) {
68
+ this.logger.error('Failed to generate installation instructions', error, {
69
+ dependency: dependency.name,
70
+ platform
71
+ });
72
+ throw error;
73
+ }
69
74
  }
70
-
75
+
71
76
  /**
72
77
  * Generate recovery suggestions for failed dependencies
73
78
  * @param {Object} failedDependency - Dependency that failed validation
74
79
  * @returns {Object} Recovery suggestions
75
80
  */
76
81
  generateRecoverySuggestions(failedDependency) {
77
- const suggestions = {
78
- immediate: [],
79
- alternative: [],
80
- troubleshooting: []
81
- };
82
+ this.logger.debug('Generating recovery suggestions', {
83
+ dependency: failedDependency.name,
84
+ errorCode: failedDependency.error?.code
85
+ });
82
86
 
83
- if (failedDependency.error) {
84
- switch (failedDependency.error.code) {
85
- case 'NOT_FOUND':
86
- suggestions.immediate.push(`Try: Install ${failedDependency.name} using your package manager`);
87
- suggestions.immediate.push(`Solution: Add ${failedDependency.name} to your system PATH`);
88
- suggestions.alternative.push(`Use portable version of ${failedDependency.name}`);
89
- suggestions.alternative.push(`Install via different package manager`);
90
- break;
91
-
92
- case 'VERSION_MISMATCH':
93
- suggestions.immediate.push(`Try: Update ${failedDependency.name} to newer version`);
94
- suggestions.immediate.push(`Solution: Use version manager to install required version`);
95
- suggestions.alternative.push(`Install specific version manually`);
96
- break;
97
-
98
- default:
99
- suggestions.immediate.push(`Try: Reinstall ${failedDependency.name}`);
100
- suggestions.immediate.push(`Solution: Check system configuration`);
101
- }
87
+ try {
88
+ const suggestions = this.recoveryService.generateRecoverySuggestions(failedDependency);
89
+
90
+ this.logger.debug('Generated recovery suggestions', {
91
+ immediate: suggestions.immediate.length,
92
+ alternative: suggestions.alternative.length,
93
+ troubleshooting: suggestions.troubleshooting.length
94
+ });
95
+
96
+ return suggestions;
97
+ } catch (error) {
98
+ this.logger.error('Failed to generate recovery suggestions', error, {
99
+ dependency: failedDependency.name
100
+ });
101
+ throw error;
102
102
  }
103
-
104
- // Add general troubleshooting guidance
105
- suggestions.troubleshooting = [
106
- 'Next steps for troubleshooting: Check system logs and package manager status',
107
- 'Verify internet connectivity for downloads',
108
- 'Try running commands with elevated privileges',
109
- 'Check for conflicting software installations'
110
- ];
111
-
112
- return suggestions;
113
103
  }
114
-
104
+
115
105
  /**
116
106
  * Generate installation instructions for multiple dependencies
117
107
  * @param {Array} dependencies - List of dependencies to install
@@ -119,446 +109,174 @@ class InstallationInstructionGenerator {
119
109
  * @returns {Object} Batch installation instructions
120
110
  */
121
111
  generateBatchInstallationInstructions(dependencies, platform = process.platform) {
122
- const batchInstructions = {
123
- platform: platform,
124
- dependencies: dependencies.map(dep => dep.name),
125
- packageManagerOptions: [],
126
- bulkCommands: [],
127
- individualInstructions: []
128
- };
129
-
130
- // Generate individual instructions
131
- for (const dependency of dependencies) {
132
- const individualInstructions = this.generateInstallationInstructions(dependency, platform);
133
- batchInstructions.individualInstructions.push({
134
- dependency: dependency.name,
135
- instructions: individualInstructions
136
- });
137
- }
138
-
139
- // Generate bulk installation commands
140
- const packageManagers = this.packageManagerService.getPackageManagersForPlatform(platform);
141
- for (const pm of packageManagers) {
142
- const packages = dependencies.map(dep =>
143
- this.packageManagerService.getPackageName(dep.name, pm.name, platform)
144
- );
112
+ this.logger.info('Generating batch installation instructions', {
113
+ count: dependencies.length,
114
+ platform
115
+ });
116
+
117
+ try {
118
+ const batchInstructions = {
119
+ platform,
120
+ dependencies: dependencies.map(dep => dep.name),
121
+ individualInstructions: []
122
+ };
145
123
 
146
- if (packages.length > 0) {
147
- const bulkCommand = this._generateBulkInstallCommand(pm, packages);
148
- batchInstructions.bulkCommands.push({
149
- packageManager: pm.name,
150
- command: bulkCommand,
151
- packages: packages
124
+ // Generate individual instructions for each dependency
125
+ for (const dependency of dependencies) {
126
+ const instructions = this.generateInstallationInstructions(dependency, platform);
127
+ batchInstructions.individualInstructions.push({
128
+ dependency: dependency.name,
129
+ instructions
152
130
  });
153
131
  }
132
+
133
+ this.logger.debug('Generated batch instructions', {
134
+ processedCount: batchInstructions.individualInstructions.length
135
+ });
136
+
137
+ return batchInstructions;
138
+ } catch (error) {
139
+ this.logger.error('Failed to generate batch installation instructions', error, {
140
+ dependencyCount: dependencies.length,
141
+ platform
142
+ });
143
+ throw error;
154
144
  }
155
-
156
- return batchInstructions;
157
145
  }
158
-
146
+
159
147
  /**
160
- * Generate upgrade instructions for outdated dependencies
148
+ * Generate upgrade instructions for outdated dependency
161
149
  * @param {Object} dependency - Dependency to upgrade
162
- * @param {string} currentVersion - Current version
163
- * @param {string} targetVersion - Target version
164
150
  * @param {string} platform - Target platform
165
151
  * @returns {Object} Upgrade instructions
166
152
  */
167
- generateUpgradeInstructions(dependency, currentVersion, targetVersion, platform = process.platform) {
168
- const upgradeInstructions = {
153
+ generateUpgradeInstructions(dependency, platform = process.platform) {
154
+ this.logger.debug('Generating upgrade instructions', {
169
155
  dependency: dependency.name,
170
- currentVersion: currentVersion,
171
- targetVersion: targetVersion,
172
- platform: platform,
173
- upgradeSteps: [],
174
- verificationSteps: [],
175
- backupRecommendations: [],
176
- troubleshootingTips: []
177
- };
178
-
179
- // Add backup recommendations
180
- upgradeInstructions.backupRecommendations = [
181
- `Backup current ${dependency.name} configuration if applicable`,
182
- 'Document current working setup before upgrading',
183
- 'Ensure you can rollback if needed'
184
- ];
185
-
186
- // Generate upgrade commands
187
- const packageManagers = this.packageManagerService.getAvailablePackageManagers(platform);
188
- for (const pm of packageManagers) {
189
- const upgradeCommand = this._generateUpgradeCommand(pm, dependency.name, platform);
190
- if (upgradeCommand) {
191
- upgradeInstructions.upgradeSteps.push({
192
- packageManager: pm.name,
193
- command: upgradeCommand,
194
- description: `Upgrade ${dependency.name} using ${pm.name}`
195
- });
196
- }
197
- }
198
-
199
- // Add verification steps
200
- upgradeInstructions.verificationSteps = [
201
- `Run: ${dependency.name} --version`,
202
- `Verify version shows ${targetVersion} or higher`,
203
- 'Test basic functionality to ensure upgrade was successful'
204
- ];
205
-
206
- // Add troubleshooting tips
207
- upgradeInstructions.troubleshootingTips = [
208
- 'Clear package manager cache if upgrade fails',
209
- 'Check for dependency conflicts',
210
- 'Restart terminal/shell after upgrade',
211
- 'Verify PATH environment variable is correct'
212
- ];
213
-
214
- return upgradeInstructions;
215
- }
216
-
217
- /**
218
- * Generate platform-specific installation guidance
219
- * @param {string} platform - Target platform
220
- * @returns {Object} Platform-specific guidance
221
- */
222
- generatePlatformGuidance(platform) {
223
- const guidance = {
224
- platform: platform,
225
- platformName: this.platformUtils.getPlatformName(platform),
226
- packageManagers: [],
227
- commonIssues: [],
228
- bestPractices: [],
229
- systemRequirements: {}
230
- };
231
-
232
- // Get package managers for platform
233
- guidance.packageManagers = this.packageManagerService.getPackageManagersForPlatform(platform)
234
- .map(pm => ({
235
- name: pm.name,
236
- description: this._getPackageManagerDescription(pm.name),
237
- installationUrl: this._getPackageManagerInstallUrl(pm.name, platform)
238
- }));
239
-
240
- // Platform-specific guidance
241
- switch (platform) {
242
- case 'win32':
243
- guidance.commonIssues = [
244
- 'PATH environment variable not updated',
245
- 'PowerShell execution policy restrictions',
246
- 'Windows Defender blocking downloads',
247
- 'Missing Visual C++ redistributables'
248
- ];
249
- guidance.bestPractices = [
250
- 'Run commands as Administrator when necessary',
251
- 'Use PowerShell instead of Command Prompt',
252
- 'Install package manager first (Chocolatey, Winget)',
253
- 'Check Windows version compatibility'
254
- ];
255
- break;
256
-
257
- case 'darwin':
258
- guidance.commonIssues = [
259
- 'Xcode Command Line Tools missing',
260
- 'System Integrity Protection (SIP) restrictions',
261
- 'Homebrew not installed or outdated',
262
- 'Architecture mismatch (Intel vs Apple Silicon)'
263
- ];
264
- guidance.bestPractices = [
265
- 'Install Xcode Command Line Tools first',
266
- 'Use Homebrew for package management',
267
- 'Check architecture compatibility (x86_64 vs arm64)',
268
- 'Update shell profile (.zshrc) for PATH changes'
269
- ];
270
- break;
271
-
272
- case 'linux':
273
- guidance.commonIssues = [
274
- 'Missing package repositories',
275
- 'Insufficient permissions',
276
- 'Outdated package lists',
277
- 'Missing dependencies'
278
- ];
279
- guidance.bestPractices = [
280
- 'Update package lists before installing',
281
- 'Use distribution-specific package manager',
282
- 'Install development tools if compiling from source',
283
- 'Check distribution version compatibility'
284
- ];
285
- break;
286
- }
287
-
288
- return guidance;
289
- }
290
-
291
- /**
292
- * Create instruction generation context
293
- * @param {Object} dependency - Dependency information
294
- * @param {string} platform - Target platform
295
- * @returns {Object} Instruction context
296
- * @private
297
- */
298
- _createInstructionContext(dependency, platform) {
299
- return {
300
- dependency,
301
- platform,
302
- platformManagers: this.packageManagerService.getPackageManagersForPlatform(platform),
303
- dependencyMapping: this.packageManagerService.config.dependencyMappings[dependency.name]
304
- };
305
- }
306
-
307
- /**
308
- * Initialize empty instructions object
309
- * @param {string} platform - Target platform
310
- * @returns {Object} Empty instructions object
311
- * @private
312
- */
313
- _initializeInstructions(platform) {
314
- return {
315
- platform: platform,
316
- packageManager: null,
317
- commands: [],
318
- packageManagerOptions: [],
319
- globalInstall: null,
320
- localInstall: null,
321
- alternativeOptions: []
322
- };
323
- }
324
-
325
- /**
326
- * Add platform-specific package managers to instructions
327
- * @param {Object} instructions - Instructions object to modify
328
- * @param {Object} context - Instruction context
329
- * @private
330
- */
331
- _addPlatformPackageManagers(instructions, context) {
332
- for (const pm of context.platformManagers) {
333
- const packageName = this._resolvePackageName(pm, context);
334
- const packageManagerOption = this._createPackageManagerOption(pm, packageName);
335
- instructions.packageManagerOptions.push(packageManagerOption);
336
- }
337
- }
338
-
339
- /**
340
- * Resolve package name for specific package manager
341
- * @param {Object} pm - Package manager configuration
342
- * @param {Object} context - Instruction context
343
- * @returns {string} Resolved package name
344
- * @private
345
- */
346
- _resolvePackageName(pm, context) {
347
- const { dependency, platform, dependencyMapping } = context;
348
-
349
- if (dependencyMapping && dependencyMapping[platform] && dependencyMapping[platform][pm.name]) {
350
- return dependencyMapping[platform][pm.name];
156
+ currentVersion: dependency.currentVersion,
157
+ targetVersion: dependency.targetVersion
158
+ });
159
+
160
+ try {
161
+ // Generate upgrade-specific instructions
162
+ const upgradeOptions = {
163
+ global: dependency.global,
164
+ version: dependency.targetVersion,
165
+ currentVersion: dependency.currentVersion
166
+ };
167
+
168
+ const packageManagerInstructions = this.packageManagerService.generateInstallationInstructions(
169
+ dependency.packageName || dependency.name,
170
+ upgradeOptions
171
+ );
172
+
173
+ const instructions = {
174
+ dependency: dependency.name,
175
+ platform,
176
+ currentVersion: dependency.currentVersion,
177
+ targetVersion: dependency.targetVersion,
178
+ packageManagers: packageManagerInstructions,
179
+ notes: [`Upgrading from ${dependency.currentVersion} to ${dependency.targetVersion}`]
180
+ };
181
+
182
+ this.logger.debug('Generated upgrade instructions', {
183
+ managersCount: packageManagerInstructions.length
184
+ });
185
+
186
+ return instructions;
187
+ } catch (error) {
188
+ this.logger.error('Failed to generate upgrade instructions', error, {
189
+ dependency: dependency.name
190
+ });
191
+ throw error;
351
192
  }
352
-
353
- return dependency.name;
354
- }
355
-
356
- /**
357
- * Create package manager option object
358
- * @param {Object} pm - Package manager configuration
359
- * @param {string} packageName - Resolved package name
360
- * @returns {Object} Package manager option
361
- * @private
362
- */
363
- _createPackageManagerOption(pm, packageName) {
364
- return {
365
- name: pm.name,
366
- command: pm.install.replace('{package}', packageName),
367
- check: pm.check.replace('{package}', packageName),
368
- packageName: packageName
369
- };
370
193
  }
371
-
194
+
372
195
  /**
373
- * Set default package manager from available options
374
- * @param {Object} instructions - Instructions object to modify
375
- * @private
196
+ * Generate recovery instructions for multiple failed dependencies
197
+ * @param {Array} failedDependencies - Array of failed dependencies
198
+ * @returns {Object} Consolidated recovery instructions
376
199
  */
377
- _setDefaultPackageManager(instructions) {
378
- if (instructions.packageManagerOptions.length > 0) {
379
- const defaultPM = instructions.packageManagerOptions[0];
380
- instructions.packageManager = defaultPM.name;
381
- instructions.commands.push(defaultPM.command);
200
+ generateBulkRecoveryInstructions(failedDependencies) {
201
+ this.logger.info('Generating bulk recovery instructions', {
202
+ count: failedDependencies.length
203
+ });
204
+
205
+ try {
206
+ const bulkRecovery = this.recoveryService.generateBulkRecoveryInstructions(failedDependencies);
207
+
208
+ this.logger.debug('Generated bulk recovery instructions', {
209
+ immediate: bulkRecovery.immediate.length,
210
+ alternative: bulkRecovery.alternative.length,
211
+ troubleshooting: bulkRecovery.troubleshooting.length
212
+ });
213
+
214
+ return bulkRecovery;
215
+ } catch (error) {
216
+ this.logger.error('Failed to generate bulk recovery instructions', error, {
217
+ dependencyCount: failedDependencies.length
218
+ });
219
+ throw error;
382
220
  }
383
221
  }
384
-
385
- /**
386
- * Handle npm package-specific instructions
387
- * @param {Object} instructions - Instructions object to modify
388
- * @param {Object} context - Instruction context
389
- * @private
390
- */
391
- _handleNpmPackageSpecific(instructions, context) {
392
- if (context.dependency.type !== 'npm_package') return;
393
-
394
- this._addNpmInstallOptions(instructions, context.dependency.name);
395
- this._ensureNpmInOptions(instructions, context.dependency.name);
396
- this._addNpmAlternatives(instructions, context.dependency.name);
397
- }
398
-
399
- /**
400
- * Add npm install options (global/local)
401
- * @param {Object} instructions - Instructions object to modify
402
- * @param {string} packageName - Package name
403
- * @private
404
- */
405
- _addNpmInstallOptions(instructions, packageName) {
406
- instructions.globalInstall = `npm install -g ${packageName}`;
407
- instructions.localInstall = `npm install ${packageName}`;
408
- }
409
-
222
+
410
223
  /**
411
- * Ensure npm is in package manager options
412
- * @param {Object} instructions - Instructions object to modify
413
- * @param {string} packageName - Package name
414
- * @private
224
+ * Generate step-by-step recovery guide
225
+ * @param {Object} failedDependency - Failed dependency information
226
+ * @returns {Array} Step-by-step recovery instructions
415
227
  */
416
- _ensureNpmInOptions(instructions, packageName) {
417
- const hasNpm = instructions.packageManagerOptions.some(pm => pm.name === 'npm');
418
- if (!hasNpm) {
419
- instructions.packageManagerOptions.unshift({
420
- name: 'npm',
421
- command: `npm install -g ${packageName}`
228
+ generateStepByStepGuide(failedDependency) {
229
+ this.logger.debug('Generating step-by-step guide', {
230
+ dependency: failedDependency.name
231
+ });
232
+
233
+ try {
234
+ const guide = this.recoveryService.generateStepByStepGuide(failedDependency);
235
+
236
+ this.logger.debug('Generated step-by-step guide', {
237
+ steps: guide.length
238
+ });
239
+
240
+ return guide;
241
+ } catch (error) {
242
+ this.logger.error('Failed to generate step-by-step guide', error, {
243
+ dependency: failedDependency.name
422
244
  });
245
+ throw error;
423
246
  }
424
247
  }
425
-
426
- /**
427
- * Add npm alternatives (yarn, pnpm)
428
- * @param {Object} instructions - Instructions object to modify
429
- * @param {string} packageName - Package name
430
- * @private
431
- */
432
- _addNpmAlternatives(instructions, packageName) {
433
- instructions.packageManagerOptions.push(
434
- { name: 'yarn', command: `yarn global add ${packageName}` },
435
- { name: 'pnpm', command: `pnpm add -g ${packageName}` }
436
- );
437
- }
438
-
439
- /**
440
- * Add alternative installation methods (private)
441
- * @param {Object} instructions - Instructions to enhance
442
- * @param {Object} dependency - Dependency information
443
- * @param {string} platform - Target platform
444
- * @private
445
- */
446
- _addAlternativeInstallationMethods(instructions, dependency, platform) {
447
- this._addDownloadLinks(instructions, dependency, platform);
448
- this._addDockerAlternative(instructions, dependency);
449
- }
450
-
248
+
451
249
  /**
452
- * Add download links for dependencies (private)
453
- * @param {Object} instructions - Instructions to enhance
454
- * @param {Object} dependency - Dependency information
250
+ * Get recommended package manager for platform
455
251
  * @param {string} platform - Target platform
456
- * @private
252
+ * @returns {string} Recommended package manager
457
253
  */
458
- _addDownloadLinks(instructions, dependency, platform) {
459
- const links = this.config.downloadLinks[dependency.name];
460
- if (!links) return;
461
-
462
- if (links.all) {
463
- instructions.alternativeOptions.push(`Download from: ${links.all}`);
464
- } else if (links[platform]) {
465
- instructions.alternativeOptions.push(`Download from: ${links[platform]}`);
254
+ getRecommendedPackageManager(platform = process.platform) {
255
+ try {
256
+ return this.packageManagerService.getRecommendedPackageManager(platform);
257
+ } catch (error) {
258
+ this.logger.error('Failed to get recommended package manager', error, { platform });
259
+ return 'npm'; // Safe fallback
466
260
  }
467
261
  }
468
-
262
+
469
263
  /**
470
- * Add Docker alternative for tools (private)
471
- * @param {Object} instructions - Instructions to enhance
472
- * @param {Object} dependency - Dependency information
473
- * @private
264
+ * Validate package manager availability
265
+ * @param {string} manager - Package manager name
266
+ * @returns {Object} Validation result
474
267
  */
475
- _addDockerAlternative(instructions, dependency) {
476
- if (dependency.type === 'tool') {
477
- instructions.alternativeOptions.push(`Use Docker container with ${dependency.name} pre-installed`);
268
+ validatePackageManager(manager) {
269
+ try {
270
+ return this.packageManagerService.validatePackageManager(manager);
271
+ } catch (error) {
272
+ this.logger.error('Failed to validate package manager', error, { manager });
273
+ return {
274
+ valid: false,
275
+ error: 'Validation failed',
276
+ suggestions: ['Try using npm as fallback']
277
+ };
478
278
  }
479
279
  }
480
-
481
- /**
482
- * Generate bulk install command for multiple packages
483
- * @param {Object} packageManager - Package manager configuration
484
- * @param {Array<string>} packages - List of packages
485
- * @returns {string} Bulk install command
486
- * @private
487
- */
488
- _generateBulkInstallCommand(packageManager, packages) {
489
- const packageList = packages.join(' ');
490
- return packageManager.install.replace('{package}', packageList);
491
- }
492
-
493
- /**
494
- * Generate upgrade command for a specific package
495
- * @param {Object} packageManager - Package manager configuration
496
- * @param {string} packageName - Package to upgrade
497
- * @param {string} platform - Target platform
498
- * @returns {string} Upgrade command
499
- * @private
500
- */
501
- _generateUpgradeCommand(packageManager, packageName, platform) {
502
- const resolvedName = this.packageManagerService.getPackageName(packageName, packageManager.name, platform);
503
-
504
- // Map package manager to upgrade commands
505
- const upgradeCommands = {
506
- 'apt': `sudo apt-get update && sudo apt-get upgrade ${resolvedName}`,
507
- 'yum': `sudo yum update ${resolvedName}`,
508
- 'dnf': `sudo dnf update ${resolvedName}`,
509
- 'pacman': `sudo pacman -S ${resolvedName}`,
510
- 'brew': `brew upgrade ${resolvedName}`,
511
- 'chocolatey': `choco upgrade ${resolvedName}`,
512
- 'winget': `winget upgrade ${resolvedName}`,
513
- 'npm': `npm update -g ${resolvedName}`,
514
- 'yarn': `yarn global upgrade ${resolvedName}`,
515
- 'pnpm': `pnpm update -g ${resolvedName}`
516
- };
517
-
518
- return upgradeCommands[packageManager.name] || null;
519
- }
520
-
521
-
522
- /**
523
- * Get package manager description
524
- * @param {string} packageManagerName - Package manager name
525
- * @returns {string} Description
526
- * @private
527
- */
528
- _getPackageManagerDescription(packageManagerName) {
529
- const descriptions = {
530
- 'apt': 'Advanced Package Tool - Debian/Ubuntu package manager',
531
- 'yum': 'Yellowdog Updater Modified - Red Hat package manager',
532
- 'dnf': 'Dandified YUM - Modern Red Hat package manager',
533
- 'pacman': 'Package Manager - Arch Linux package manager',
534
- 'brew': 'Homebrew - macOS package manager',
535
- 'chocolatey': 'Chocolatey - Windows package manager',
536
- 'winget': 'Windows Package Manager - Microsoft package manager',
537
- 'npm': 'Node Package Manager - JavaScript package manager',
538
- 'yarn': 'Yarn - Fast JavaScript package manager',
539
- 'pnpm': 'pnpm - Efficient JavaScript package manager'
540
- };
541
- return descriptions[packageManagerName] || `${packageManagerName} package manager`;
542
- }
543
-
544
- /**
545
- * Get package manager installation URL
546
- * @param {string} packageManagerName - Package manager name
547
- * @param {string} platform - Target platform
548
- * @returns {string} Installation URL
549
- * @private
550
- */
551
- _getPackageManagerInstallUrl(packageManagerName, platform) {
552
- const installUrls = {
553
- 'brew': 'https://brew.sh/',
554
- 'chocolatey': 'https://chocolatey.org/install',
555
- 'winget': 'https://docs.microsoft.com/en-us/windows/package-manager/winget/',
556
- 'npm': 'https://nodejs.org/en/download/',
557
- 'yarn': 'https://yarnpkg.com/getting-started/install',
558
- 'pnpm': 'https://pnpm.io/installation'
559
- };
560
- return installUrls[packageManagerName] || null;
561
- }
562
280
  }
563
281
 
564
282
  module.exports = InstallationInstructionGenerator;