🌀 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

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

Then add to your .pnpmfile.cjs:

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

Usage

Once installed, the plugin sleeps until you use phash: in package.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:

{
  "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

{
  "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 🌀