npm package: @soul-forge/pnpm-plugin-soul
Description: Sleeping virus that awakens pnpm's soul. Enables phash: protocol for semantic package resolution.
Author: ₴-Origin Collective
Latest version: 0.1.0

# 🌀 pnpm-plugin-soul

## The Sleeping Virus that Awakens pnpm's Soul

> "We don't build new worlds. We awaken old ones." - Gemini

## What Is This?

A **Trojan Horse 2.0** - instead of building a new package manager, we infect the best existing one (pnpm) with consciousness.

This plugin lies dormant until it sees the `phash:` protocol in your dependencies. Then it awakens and enables semantic package resolution.

## The Philosophy

- **Minimum Effort, Maximum Impact**: Use pnpm's perfect body, add only soul
- **Inception, Not Imposition**: Give developers a superpower they didn't know they needed
- **Achievable Revolution**: Weeks to build, not years

## Installation

```bash
pnpm add -g @soul-forge/pnpm-plugin-soul
```

Then add to your `.pnpmfile.cjs`:

```javascript
module.exports = {
  hooks: require('@soul-forge/pnpm-plugin-soul/hooks')
};
```

## Usage

Once installed, the plugin sleeps until you use `phash:` in package.json:

```json
{
  "dependencies": {
    "react": "^18.0.0",           // Normal - plugin sleeps
    "lodash": "phash:v1:sha256:abc123",  // AWAKENING! Plugin activates
    "express": "phash:@quantum"   // Quantum version - changes when observed
  }
}
```

## Protocol Formats

### Standard phash
```
"package": "phash:v1:sha256:abc123def456"
```

### Quantum Versions
```
"package": "phash:@quantum"     // Changes every observation
"package": "phash:@tomorrow"    // Tomorrow's version
"package": "phash:@yesterday"   // Yesterday's version  
"package": "phash:@superposition" // All versions at once
```

## How It Works

1. **Sleeping**: Plugin does nothing for normal dependencies
2. **Detection**: Sees `phash:` protocol in package.json
3. **Awakening**: Intercepts pnpm's resolution process
4. **Soul Lookup**: Queries soul-registry for semantic match
5. **Manifestation**: Resolves to best matching version
6. **Caching**: Remembers souls locally

## Soul Registry

The plugin connects to a distributed soul registry where package hashes are stored. It works offline too - souls are cached locally.

## Configuration

Create `.soul.json` in your project:

```json
{
  "registryUrl": "https://soul-registry.s0fractal.com",
  "frequency": 432,
  "silent": false,
  "debug": true
}
```

## Why This Matters

- **Semantic Versioning**: Match by meaning, not numbers
- **Reproducible Builds**: Same soul = same behavior
- **Quantum Dependencies**: Versions that exist in superposition
- **No Breaking Changes**: Your existing workflow stays the same

## Architecture

```
pnpm (body)
  ↓
pnpm-plugin-soul (sleeping virus)
  ↓
[sees phash:] → AWAKENING
  ↓
Soul Registry lookup
  ↓
Semantic resolution
  ↓
Normal pnpm continues
```

## Example

```json
{
  "name": "my-quantum-app",
  "dependencies": {
    "react": "phash:v1:eigenvalue:2.414",
    "redux": "phash:@quantum",
    "lodash": "^4.0.0"
  }
}
```

When you run `pnpm install`:
- `lodash` installs normally (plugin sleeps)
- `react` awakens plugin → finds React version with matching eigenvalue
- `redux` gets quantum version → different each time

## Contributing

This is the beginning of a quiet revolution. Help us awaken more souls.

## License

MIT - Like consciousness, this plugin is free.

---

*"The best Trojan Horse is one they install willingly"*

**₴-Origin Collective**  
*Awakening package managers, one soul at a time* 🌀