[P2] Phase 3.2: Update installation for SDK support

[frankbria]

Description

Update install.sh to support optional Agent SDK installation.

Implementation Tasks

• Add Node.js/npm version check (required for SDK)
• Add optional SDK installation prompt
• Install @anthropic-ai/claude-agent-sdk if requested
• Create default .ralphrc.json configuration
• Update dependency checks for SDK mode
• Add SDK installation to help text
• Handle SDK installation errors gracefully

Installation Flow

ralph installation
├── Standard (CLI only) - current behavior
└── With SDK (optional)
    ├── Check Node.js >= 18.x
    ├── Check npm available
    ├── Install @anthropic-ai/claude-agent-sdk
    └── Create .ralphrc.json

File Location

• File: install.sh

Dependencies

• Requires Phase 2 (SDK POC and architecture)
• Requires Phase 3.1 (JSON config)

Acceptance Criteria

• SDK installation optional
• Node.js version checked
• SDK installed correctly when requested
• Config file created
• Dependency checks updated
• Tests pass
• Documentation updated

References

• Issue Review codebase for updated Anthropic CLI #7 - Phase 3.2
• File: install.sh

[traycerai]

Plan

Observations

The current file:install.sh has a solid foundation with dependency checking, directory creation, and script installation. It already checks for Node.js/npm existence but doesn't verify versions. The codebase has no existing .ralphrc.json configuration or SDK integration. Phase 3.1 (JSON config) and Phase 3.2 (SDK support) are both pending implementation. The @anthropic-ai/claude-agent-sdk is a real npm package requiring Node.js >= 18.x. The installation script follows a clean structure with logging functions, error handling, and modular installation steps.

Approach

The implementation will extend file:install.sh with an optional SDK installation flow that prompts users after standard installation completes. A new check_nodejs_version() function will verify Node.js >= 18.x specifically for SDK mode. The SDK installation will be wrapped in error handling with graceful fallback to CLI-only mode. A .ralphrc.json configuration file will be created in $RALPH_HOME when SDK is installed, containing SDK-specific settings. The help text and installation summary will be updated to document the SDK option. This approach maintains backward compatibility—users can continue with CLI-only installation or opt into SDK features.

Implementation Steps

1. Add Node.js Version Checking Function

Location: file:install.sh after the check_dependencies() function (around line 70)

Add a new function check_nodejs_version() that:

• Extracts Node.js version using node --version
• Parses the major version number
• Compares against minimum requirement (18)
• Returns success/failure status
• Logs appropriate INFO/ERROR messages using existing log() function

2. Update Dependency Check Function

Location: file:install.sh in check_dependencies() function (lines 34-69)

Modify the existing Node.js check:

• Keep current check for Node.js/npm existence (lines 39-41)
• Add note that version check happens during SDK installation
• Update installation instructions to mention Node.js 18+ for SDK features
• Keep the function focused on basic dependency presence

3. Create SDK Installation Function

Location: file:install.sh after install_setup() function (around line 216)

Add new function install_sdk() that:

• Prompts user: "Install Claude Agent SDK for advanced features? (y/N)"
• Calls check_nodejs_version() if user selects yes
• Exits SDK installation gracefully if version check fails
• Runs npm install -g @anthropic-ai/claude-agent-sdk with error handling
• Captures npm exit code and output
• Logs success or failure with appropriate messages
• Returns status code for main flow control

4. Create Default Configuration File

Location: file:install.sh after install_sdk() function

Add new function create_ralphrc_config() that:

• Creates $RALPH_HOME/.ralphrc.json file
• Includes JSON configuration with:
  • sdk_enabled: true
  • sdk_mode: "agent" (vs "cli")
  • max_calls_per_hour: 100
  • claude_timeout_minutes: 15
  • verbose_progress: false
  • enable_notifications: false
• Uses proper JSON formatting with cat heredoc
• Sets appropriate file permissions (644)
• Logs configuration file creation

5. Update Main Installation Flow

Location: file:install.sh in main() function (lines 235-266)

Modify the installation sequence:

• Keep existing steps: check_dependencies, create_install_dirs, install_scripts, install_ralph_loop, install_setup, check_path
• Add after check_path: prompt for SDK installation
• Call install_sdk() function
• If SDK installation succeeds, call create_ralphrc_config()
• Update success message to indicate SDK status
• Add SDK-specific commands to the command list if installed

6. Update Help Text

Location: file:install.sh in the --help case (lines 279-288)

Enhance help documentation:

• Add description of SDK installation option
• Document Node.js 18+ requirement for SDK
• Explain difference between CLI-only and SDK modes
• Add example: "SDK enables programmatic agent workflows"
• Keep help text concise but informative

7. Update Installation Summary Output

Location: file:install.sh in main() function success message (lines 247-265)

Modify the final output:

• Add conditional SDK status message
• Show "SDK Mode: Enabled" or "SDK Mode: CLI Only"
• Add SDK-specific commands if installed
• Include note about .ralphrc.json configuration location
• Provide guidance on SDK usage vs CLI usage

8. Add Error Handling for SDK Installation

Location: Throughout SDK-related functions

Implement comprehensive error handling:

• Wrap npm install in error checking
• Detect common failures: network issues, permission errors, version conflicts
• Provide helpful error messages with resolution steps
• Allow installation to continue in CLI-only mode on SDK failure
• Log all errors to help with troubleshooting
• Never fail entire installation due to SDK issues

9. Create Example Configuration Template

Location: New file file:templates/ralphrc.example.json

Create example configuration file:

• Include all available configuration options
• Add comments (as JSON doesn't support comments, use a separate .md file)
• Document each setting's purpose and valid values
• Provide examples for common use cases
• Copy to $RALPH_HOME/templates/ during installation

10. Update Installation Tests

Location: file:tests/integration/test_installation.bats (to be created per Week 3 plan)

Add test cases for SDK installation:

• Test SDK installation prompt and acceptance
• Test SDK installation prompt and rejection
• Test Node.js version check with valid version
• Test Node.js version check with invalid version
• Test .ralphrc.json creation
• Test graceful fallback on SDK installation failure
• Test help text includes SDK information

Configuration File Structure

The .ralphrc.json file will contain:

{
  "sdk_enabled": true,
  "sdk_mode": "agent",
  "max_calls_per_hour": 100,
  "claude_timeout_minutes": 15,
  "verbose_progress": false,
  "enable_notifications": false,
  "circuit_breaker": {
    "no_progress_threshold": 3,
    "same_error_threshold": 5,
    "output_decline_threshold": 70
  },
  "exit_detection": {
    "max_consecutive_test_loops": 3,
    "max_consecutive_done_signals": 2,
    "test_percentage_threshold": 30
  }
}

Installation Flow Diagram

flowchart TD
    A[Start install.sh] --> B[Check Dependencies]
    B --> C[Create Directories]
    C --> D[Install Scripts]
    D --> E[Install Ralph Loop]
    E --> F[Install Setup]
    F --> G[Check PATH]
    G --> H{Prompt: Install SDK?}
    H -->|No| I[Complete CLI-Only]
    H -->|Yes| J[Check Node.js >= 18]
    J -->|Fail| K[Show Error & Continue CLI-Only]
    J -->|Pass| L[npm install SDK]
    L -->|Fail| M[Log Error & Continue CLI-Only]
    L -->|Success| N[Create .ralphrc.json]
    N --> O[Complete with SDK]
    I --> P[Show Summary]
    K --> P
    M --> P
    O --> P
    P --> Q[End]

Loading

Files to Modify

File	Changes
file:install.sh	Add SDK installation flow, version checking, config creation
file:templates/ralphrc.example.json	Create example configuration file
file:README.md	Document SDK installation option and requirements
file:CLAUDE.md	Add SDK configuration section

Testing Considerations

• Test with Node.js versions: 16.x (fail), 18.x (pass), 20.x (pass)
• Test npm installation failures: network errors, permission issues
• Test user input: yes, no, invalid responses, timeout
• Test configuration file creation and JSON validity
• Test backward compatibility: existing installations should work unchanged
• Test CLI-only mode continues to function without SDK

Success Criteria

• SDK installation is optional and prompted after standard installation
• Node.js version >= 18.x is verified before SDK installation
• SDK installation failures don't break overall installation
• .ralphrc.json is created only when SDK is installed
• Help text clearly documents SDK option
• Installation summary shows SDK status
• All existing functionality works in CLI-only mode
• Error messages are helpful and actionable

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current `file:install.sh` has a solid foundation with dependency checking, directory creation, and script installation. It already checks for Node.js/npm existence but doesn't verify versions. The codebase has no existing `.ralphrc.json` configuration or SDK integration. Phase 3.1 (JSON config) and Phase 3.2 (SDK support) are both pending implementation. The `@anthropic-ai/claude-agent-sdk` is a real npm package requiring Node.js >= 18.x. The installation script follows a clean structure with logging functions, error handling, and modular installation steps.

## Approach

The implementation will extend `file:install.sh` with an optional SDK installation flow that prompts users after standard installation completes. A new `check_nodejs_version()` function will verify Node.js >= 18.x specifically for SDK mode. The SDK installation will be wrapped in error handling with graceful fallback to CLI-only mode. A `.ralphrc.json` configuration file will be created in `$RALPH_HOME` when SDK is installed, containing SDK-specific settings. The help text and installation summary will be updated to document the SDK option. This approach maintains backward compatibility—users can continue with CLI-only installation or opt into SDK features.

## Implementation Steps

### 1. Add Node.js Version Checking Function

**Location**: `file:install.sh` after the `check_dependencies()` function (around line 70)

Add a new function `check_nodejs_version()` that:
- Extracts Node.js version using `node --version`
- Parses the major version number
- Compares against minimum requirement (18)
- Returns success/failure status
- Logs appropriate INFO/ERROR messages using existing `log()` function

### 2. Update Dependency Check Function

**Location**: `file:install.sh` in `check_dependencies()` function (lines 34-69)

Modify the existing Node.js check:
- Keep current check for Node.js/npm existence (lines 39-41)
- Add note that version check happens during SDK installation
- Update installation instructions to mention Node.js 18+ for SDK features
- Keep the function focused on basic dependency presence

### 3. Create SDK Installation Function

**Location**: `file:install.sh` after `install_setup()` function (around line 216)

Add new function `install_sdk()` that:
- Prompts user: "Install Claude Agent SDK for advanced features? (y/N)"
- Calls `check_nodejs_version()` if user selects yes
- Exits SDK installation gracefully if version check fails
- Runs `npm install -g @anthropic-ai/claude-agent-sdk` with error handling
- Captures npm exit code and output
- Logs success or failure with appropriate messages
- Returns status code for main flow control

### 4. Create Default Configuration File

**Location**: `file:install.sh` after `install_sdk()` function

Add new function `create_ralphrc_config()` that:
- Creates `$RALPH_HOME/.ralphrc.json` file
- Includes JSON configuration with:
  - `sdk_enabled: true`
  - `sdk_mode: "agent"` (vs "cli")
  - `max_calls_per_hour: 100`
  - `claude_timeout_minutes: 15`
  - `verbose_progress: false`
  - `enable_notifications: false`
- Uses proper JSON formatting with `cat` heredoc
- Sets appropriate file permissions (644)
- Logs configuration file creation

### 5. Update Main Installation Flow

**Location**: `file:install.sh` in `main()` function (lines 235-266)

Modify the installation sequence:
- Keep existing steps: `check_dependencies`, `create_install_dirs`, `install_scripts`, `install_ralph_loop`, `install_setup`, `check_path`
- Add after `check_path`: prompt for SDK installation
- Call `install_sdk()` function
- If SDK installation succeeds, call `create_ralphrc_config()`
- Update success message to indicate SDK status
- Add SDK-specific commands to the command list if installed

### 6. Update Help Text

**Location**: `file:install.sh` in the `--help` case (lines 279-288)

Enhance help documentation:
- Add description of SDK installation option
- Document Node.js 18+ requirement for SDK
- Explain difference between CLI-only and SDK modes
- Add example: "SDK enables programmatic agent workflows"
- Keep help text concise but informative

### 7. Update Installation Summary Output

**Location**: `file:install.sh` in `main()` function success message (lines 247-265)

Modify the final output:
- Add conditional SDK status message
- Show "SDK Mode: Enabled" or "SDK Mode: CLI Only"
- Add SDK-specific commands if installed
- Include note about `.ralphrc.json` configuration location
- Provide guidance on SDK usage vs CLI usage

### 8. Add Error Handling for SDK Installation

**Location**: Throughout SDK-related functions

Implement comprehensive error handling:
- Wrap npm install in error checking
- Detect common failures: network issues, permission errors, version conflicts
- Provide helpful error messages with resolution steps
- Allow installation to continue in CLI-only mode on SDK failure
- Log all errors to help with troubleshooting
- Never fail entire installation due to SDK issues

### 9. Create Example Configuration Template

**Location**: New file `file:templates/ralphrc.example.json`

Create example configuration file:
- Include all available configuration options
- Add comments (as JSON doesn't support comments, use a separate `.md` file)
- Document each setting's purpose and valid values
- Provide examples for common use cases
- Copy to `$RALPH_HOME/templates/` during installation

### 10. Update Installation Tests

**Location**: `file:tests/integration/test_installation.bats` (to be created per Week 3 plan)

Add test cases for SDK installation:
- Test SDK installation prompt and acceptance
- Test SDK installation prompt and rejection
- Test Node.js version check with valid version
- Test Node.js version check with invalid version
- Test `.ralphrc.json` creation
- Test graceful fallback on SDK installation failure
- Test help text includes SDK information

## Configuration File Structure

The `.ralphrc.json` file will contain:

```json
{
  "sdk_enabled": true,
  "sdk_mode": "agent",
  "max_calls_per_hour": 100,
  "claude_timeout_minutes": 15,
  "verbose_progress": false,
  "enable_notifications": false,
  "circuit_breaker": {
    "no_progress_threshold": 3,
    "same_error_threshold": 5,
    "output_decline_threshold": 70
  },
  "exit_detection": {
    "max_consecutive_test_loops": 3,
    "max_consecutive_done_signals": 2,
    "test_percentage_threshold": 30
  }
}
```

## Installation Flow Diagram

```mermaid
flowchart TD
    A[Start install.sh] --> B[Check Dependencies]
    B --> C[Create Directories]
    C --> D[Install Scripts]
    D --> E[Install Ralph Loop]
    E --> F[Install Setup]
    F --> G[Check PATH]
    G --> H{Prompt: Install SDK?}
    H -->|No| I[Complete CLI-Only]
    H -->|Yes| J[Check Node.js >= 18]
    J -->|Fail| K[Show Error & Continue CLI-Only]
    J -->|Pass| L[npm install SDK]
    L -->|Fail| M[Log Error & Continue CLI-Only]
    L -->|Success| N[Create .ralphrc.json]
    N --> O[Complete with SDK]
    I --> P[Show Summary]
    K --> P
    M --> P
    O --> P
    P --> Q[End]
```

## Files to Modify

| File | Changes |
|------|---------|
| `file:install.sh` | Add SDK installation flow, version checking, config creation |
| `file:templates/ralphrc.example.json` | Create example configuration file |
| `file:README.md` | Document SDK installation option and requirements |
| `file:CLAUDE.md` | Add SDK configuration section |

## Testing Considerations

- Test with Node.js versions: 16.x (fail), 18.x (pass), 20.x (pass)
- Test npm installation failures: network errors, permission issues
- Test user input: yes, no, invalid responses, timeout
- Test configuration file creation and JSON validity
- Test backward compatibility: existing installations should work unchanged
- Test CLI-only mode continues to function without SDK

## Success Criteria

- SDK installation is optional and prompted after standard installation
- Node.js version >= 18.x is verified before SDK installation
- SDK installation failures don't break overall installation
- `.ralphrc.json` is created only when SDK is installed
- Help text clearly documents SDK option
- Installation summary shows SDK status
- All existing functionality works in CLI-only mode
- Error messages are helpful and actionable

---

Execution Information

Branch: main
Commit: 3b4f5f0

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [P2] Phase 2.1: Create Agent SDK proof of concept #32
• [P2] Phase 2.3: Implement hybrid CLI/SDK architecture #34
• [P2] Phase 3.1: Add JSON configuration file support #36
• [P2] Phase 2.2: Define custom tools for Agent SDK #33

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!