﻿# 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. Confirm the macOS version and CPU architecture satisfy the package requirements.
2. Check the Node.js version: Run `node --version`
3. Check the 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)"
```

### Node.js Installation

Install Node.js using Homebrew:

```bash
brew install node
```

Verify installation: `node --version`

### OpenSpec Installation

OpenSpec installs with the package manager bundled in Node.js, so no standalone npm prerequisite is required.

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

Verify installation: `openspec --version`

## Dependency Requirements

The following dependency version requirements are pre-populated in this prompt and ready to use:

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

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

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



## Troubleshooting

### Homebrew Issues

```bash
brew update
brew doctor
```

### Version Mismatch

Use the version requirements listed in this prompt and upgrade or downgrade according to each dependency's installHint.

**Node.js version mismatch**:
```bash
brew upgrade node
```

**OpenSpec version mismatch**:
```bash
npm install @fission-ai/openspec@minimum-version -g
```

### Permission Issues

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

## Verification Checklist

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

```bash
uname -m
node --version
openspec --version
```

## Execution Boundary (Mandatory)

- The only required action after installation is dependency status checking.
- Do not attempt to start any service.
- Do not perform extra initialization tasks.
- Do not trigger post-install workflows unrelated to dependency checks.
- In non-interactive mode, do not ask interactive questions; use deterministic defaults and record assumptions in the output.
- The final output must be: installation completed + dependency check results.

## 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 Value | Requirement | Notes |
|------------|--------|---------------|-------------|-------|
| System Compatibility | ✓ Confirmed | macOS Apple Silicon / Intel | Matches package requirements | |
| Node.js | ✓ Installed | 24.12.0 | >= 20.11.0 | |
| OpenSpec | ✓ Installed | 1.0.5 | 1.0.0 - < 2.0.0 | |

## Summary
- Required dependencies: 3/3 satisfied ✓
```

**Notes**:
- **Status**: Use "✓ Installed", "✗ Not Installed", "⚠ Version Mismatch"
- **Current Value**: Actual system information or version obtained from the verification commands
- **Requirement**: Requirement listed in this prompt
- **Notes**: Any follow-up action or compatibility note

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

## macOS Specific Notes

- Use the built-in Terminal or iTerm2 when available
- Replace `~/.bashrc` with `~/.zshrc` if your shell profile differs
- OpenSpec uses the package manager bundled with Node.js, so no standalone npm prerequisite is needed
