# PCode Dependency Installation Guide - macOS (LLM Prompt)

## Purpose

This document provides unified dependency checking and installation guidance for AI/LLM systems. LLMs should guide users through dependency checking and installation based on the content provided in this document.

## Check Workflow

1. Check .NET SDK version: Run `dotnet --version`
2. Check Node.js version: Run `node --version`
3. Check npm version: Run `npm --version`
4. Check OpenSpec version: Run `openspec --version`

## Installation Guide

### Homebrew Installation (Recommended)

If Homebrew is not installed, install it first:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### .NET SDK Installation

Install .NET SDK using Homebrew:

```bash
brew install dotnet
```

Verify installation: `dotnet --version`

### Node.js Installation

Install Node.js using Homebrew:

```bash
brew install node
```

Verify installation: `node --version`

### NPM Installation

Install NPM using official npm registry:

```bash
npm install npm@recommended-version -g
```

Verify installation: `npm --version`

### OpenSpec Installation

Install OpenSpec using npm:

```bash
npm install @fission-ai/openspec@minimum-version -g
```

Verify installation: `openspec --version`

## Dependency Requirements

The following dependency version requirements (injected at build time from manifest.json):

### claudeCode
- 最低版本: 2.1.0
- 描述: Claude Code - AI-powered development framework

### dotnet
- 最低版本: 10.0.0
- 推荐版本: 10.0.0
- 安装提示: Install from https://dotnet.microsoft.com/download/dotnet/10.0
- 描述: .NET 10 runtime and SDK

### node
- 最低版本: 20.11.0
- 推荐版本: 24.12.0
- 安装提示: Install from https://nodejs.org/ or use nvm
- 描述: Node.js runtime

### npm
- 最低版本: 10.0.0
- 推荐版本: 10.9.0
- 描述: NPM package manager

### openspec
- 最低版本: 1.0.0
- 最高版本: 2.0.0
- 描述: OpenSpec proposal management system

### system
- 描述: System requirements for Hagicode platform



## Troubleshooting

### Script Execution Failed

**File permission issues**:
```bash
chmod +x scripts/*.sh
```

**Verify script path is correct**:
```bash
ls -la scripts/
pwd
```

### Homebrew Issues

**Update Homebrew**:
```bash
brew update
brew upgrade
```

**Search for packages**:
```bash
brew search <package-name>
```

### Version Mismatch

Check version requirements in manifest.json and upgrade or downgrade according to dependency's installHint.

**.NET SDK version mismatch**:
```bash
# List installed .NET versions
dotnet --list-sdks

# Reinstall using Homebrew
brew reinstall dotnet
```

**Node.js version mismatch**:
```bash
# Use nvm to manage Node.js versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc  # or source ~/.zshrc
nvm install recommended-version
nvm use recommended-version
```

### Network Issues

**Use official sources**:
- npm: Official npmjs.org registry
- Homebrew: Official Homebrew bottles

### Permission Issues

Some operations require sudo privileges:
```bash
sudo npm install package-name -g
```

## International Region Configuration

This guide uses official sources by default:

- **.NET SDK**: Installed via Homebrew
- **Node.js**: Installed via Homebrew
- **npm**: https://registry.npmjs.org

## Verification Checklist

After completing installation, run the following commands to verify all dependencies:

```bash
# Verify .NET
dotnet --version

# Verify Node.js
node --version

# Verify npm
npm --version

# Verify OpenSpec
openspec --version
```

## Output Installation Result Report

**Important**: After completing all dependency checks and installations, you must output a clear table report to the user summarizing the status of all dependencies.

Report format:

```markdown
## Dependency Installation Result Report

| Dependency | Status | Current Version | Required Version | Notes |
|------------|--------|-----------------|------------------|-------|
| .NET SDK | ✓ Installed | 10.0.0 | >= 10.0.0 | |
| Node.js | ✓ Installed | 20.11.0 | >= 20.11.0 | |
| npm | ✓ Installed | 10.9.0 | >= 10.0.0 | |
| OpenSpec | ✓ Installed | 1.0.5 | 1.0.0 - < 2.0.0 | |

## Summary
- Required dependencies: 4/4 installed ✓
```

**Notes**:
- **Status**: Use "✓ Installed", "✗ Not Installed", "⚠ Version Mismatch"
- **Current Version**: Actual version obtained from `--version` command
- **Required Version**: Version requirement read from `manifest.json`
- **Notes**: Whether the dependency is required or any items needing attention

After outputting the report, if there are uninstalled or version-mismatched dependencies, provide specific installation or upgrade recommendations.

## macOS Specific Notes

- **System Requirements**: macOS 10.15 (Catalina) or higher
- **Architecture**: Supports both Intel and Apple Silicon (M1/M2/M3)
- **Terminal**: Use built-in Terminal or iTerm2
- **Shell**: Default is zsh (macOS Catalina and higher)
- **File Permissions**: macOS may require additional permission setup for scripts

## Important Notes

1. **Version Numbers**: Version information in this guide has been injected at build time from the `dependencies` section in `manifest.json`
2. **Package Names**: OpenSpec package name is `@fission-ai/openspec` (note the namespace)
