@oh-my-pi/cli 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Check (lint + typecheck)
+        run: bun run check
+
+      - name: Build
+        run: bun run build
+
+      - name: Test CLI
+        run: |
+          bun dist/cli.js --version
+          bun dist/cli.js --help

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish @oh-my-pi/cli
+        run: npm publish --access public --provenance
+
+      - name: Publish @oh-my-pi/subagents
+        working-directory: plugins/subagents
+        run: npm publish --access public --provenance
+
+      - name: Publish @oh-my-pi/metal-theme
+        working-directory: plugins/metal-theme
+        run: npm publish --access public --provenance

package/CHECK.md

@@ -0,0 +1,352 @@
+# Implementation Review Checklist
+
+Review the oh-my-pi implementation against these requirements. For each item, verify it works correctly and check the listed edge cases.
+
+---
+
+## 1. Install Command (`omp install`)
+
+### Core functionality
+- [ ] `omp install pkg-name` installs from npm
+- [ ] `omp install pkg@version` respects version specifier
+- [ ] `omp install @scope/pkg` handles scoped packages
+- [ ] `omp install ./path` copies local directory
+- [ ] `omp install ~/path` expands home directory
+- [ ] `omp install` (no args) installs from plugins.json
+- [ ] Creates symlinks for each `omp.install` entry
+
+### Edge cases
+- [ ] Package not found on npm → clear error message
+- [ ] Invalid version specifier → graceful failure
+- [ ] Local path doesn't exist → error before any changes
+- [ ] `omp.install` has missing source file → skip with warning, continue others
+- [ ] Circular dependencies between plugins → handled without infinite loop
+- [ ] Nested dependencies with omp field → all get symlinked
+- [ ] Package has no `omp` field → installs but no symlinks (warning?)
+- [ ] Network failure mid-install → rollback partial install
+- [ ] Disk full → appropriate error
+- [ ] Symlink target directory doesn't exist → creates parent dirs
+- [ ] `omp install` with empty plugins.json → helpful message
+
+### Flags
+- [ ] `--global` installs to ~/.pi/plugins/
+- [ ] `--save` adds to plugins.json
+- [ ] `--save-dev` adds to devDependencies
+- [ ] `--force` overwrites conflicts without prompting
+- [ ] `--json` outputs JSON format
+
+---
+
+## 2. Conflict Detection
+
+### Core functionality
+- [ ] Detects when two plugins install to same destination
+- [ ] Interactive prompt offers choices: plugin1, plugin2, abort
+- [ ] User can select which plugin wins
+- [ ] Abort rolls back the install
+
+### Edge cases
+- [ ] Three+ plugins with same destination → all listed
+- [ ] Conflict with already-installed plugin → prompt before npm install
+- [ ] Conflict within same plugin's install array (duplicate dest) → error
+- [ ] `--force` skips all prompts → overwrites
+- [ ] Non-interactive terminal (CI) → fail or use --force
+
+---
+
+## 3. Uninstall Command (`omp uninstall`)
+
+### Core functionality
+- [ ] `omp uninstall pkg` removes package
+- [ ] Removes all symlinks from `omp.install`
+- [ ] Removes from package.json/plugins.json
+
+### Edge cases
+- [ ] Plugin not installed → clear error
+- [ ] Symlink already deleted manually → graceful (ENOENT ignored)
+- [ ] Symlink replaced by real file → remove anyway or warn?
+- [ ] Plugin has dependencies that other plugins also use → don't break them
+- [ ] Partial uninstall (some symlinks fail) → report what failed
+
+---
+
+## 4. Update Command (`omp update`)
+
+### Core functionality
+- [ ] `omp update` updates all plugins
+- [ ] `omp update pkg` updates specific plugin
+- [ ] Respects semver ranges from plugins.json
+- [ ] Re-creates symlinks after update
+
+### Edge cases
+- [ ] Package already at latest → no-op with message
+- [ ] Major version available but range is `^` → doesn't update
+- [ ] Package removed from npm → error handling
+- [ ] Update changes `omp.install` entries → old symlinks removed, new created
+- [ ] Linked (dev) plugins → skipped with message
+
+---
+
+## 5. List Command (`omp list`)
+
+### Core functionality
+- [ ] Shows all installed plugins
+- [ ] Shows version for each
+- [ ] Shows (linked) badge for dev plugins
+
+### Edge cases
+- [ ] No plugins installed → helpful message
+- [ ] Plugin in plugins.json but not in node_modules → show as broken
+- [ ] Corrupt package.json → graceful error
+- [ ] `--json` output is valid JSON
+
+---
+
+## 6. Link Command (`omp link`)
+
+### Core functionality
+- [ ] `omp link ./path` creates symlink to source directory
+- [ ] Marks as linked in manifest
+- [ ] Creates symlinks from `omp.install`
+
+### Edge cases
+- [ ] Path doesn't exist → error
+- [ ] Path has no package.json → uses directory name, creates minimal
+- [ ] Path has omp.json (legacy) → converts to package.json format
+- [ ] Already linked → re-link or error?
+- [ ] `-n, --name` overrides plugin name
+- [ ] Linked plugin updated externally → symlinks still work
+
+---
+
+## 7. Init Command (`omp init`)
+
+### Core functionality
+- [ ] Creates `.pi/plugins.json` in current directory
+- [ ] Correct initial structure: `{ "plugins": {}, "disabled": [] }`
+
+### Edge cases
+- [ ] File already exists → error unless `--force`
+- [ ] `.pi/` directory doesn't exist → creates it
+- [ ] No write permission → clear error
+
+---
+
+## 8. Search Command (`omp search`)
+
+### Core functionality
+- [ ] `omp search query` searches npm for `keywords:omp-plugin`
+- [ ] Shows name, version, description
+
+### Edge cases
+- [ ] No results → helpful message
+- [ ] npm registry unavailable → timeout with error
+- [ ] Very long description → truncated
+- [ ] `--limit` respected
+- [ ] Special characters in query → properly escaped
+
+---
+
+## 9. Info Command (`omp info`)
+
+### Core functionality
+- [ ] `omp info pkg` shows package details
+- [ ] Shows: name, version, description, dependencies, omp.install entries
+
+### Edge cases
+- [ ] Package not found → clear error
+- [ ] Package exists but no omp field → show warning
+- [ ] `--versions` shows available versions
+- [ ] `--json` valid JSON output
+
+---
+
+## 10. Outdated Command (`omp outdated`)
+
+### Core functionality
+- [ ] Lists plugins with newer versions available
+- [ ] Shows current, wanted, latest columns
+
+### Edge cases
+- [ ] All up to date → "All plugins up to date"
+- [ ] npm outdated returns exit code 1 → still parses output
+- [ ] Plugin not on npm anymore → shown as error row
+- [ ] Linked plugins → excluded from check
+
+---
+
+## 11. Doctor Command (`omp doctor`)
+
+### Core functionality
+- [ ] Checks for broken symlinks
+- [ ] Checks for conflicts
+- [ ] Reports missing dependencies
+
+### Edge cases
+- [ ] No issues → "All good"
+- [ ] Symlink target deleted → reported as broken
+- [ ] Symlink replaced by real file → reported
+- [ ] `--fix` repairs broken symlinks
+- [ ] `--fix` can't fix conflict → reports
+
+---
+
+## 12. Create Command (`omp create`)
+
+### Core functionality
+- [ ] `omp create my-plugin` scaffolds new plugin
+- [ ] Creates package.json with omp field
+- [ ] Creates directory structure
+
+### Edge cases
+- [ ] Directory already exists → error
+- [ ] Invalid plugin name (spaces, special chars) → normalized or error
+- [ ] `--description` sets description
+- [ ] `--author` sets author
+
+---
+
+## 13. Why Command (`omp why`)
+
+### Core functionality
+- [ ] `omp why agent/themes/dark.json` shows which plugin installed it
+- [ ] Shows plugin name and source path
+
+### Edge cases
+- [ ] File not installed by any plugin → "Not installed by omp"
+- [ ] File is manually created (not symlink) → detect and report
+- [ ] Relative vs absolute path → both work
+- [ ] File doesn't exist → appropriate error
+
+---
+
+## 14. Enable/Disable Commands
+
+### Core functionality
+- [ ] `omp disable pkg` removes symlinks, keeps in node_modules
+- [ ] `omp enable pkg` restores symlinks
+- [ ] Disabled list persisted
+
+### Edge cases
+- [ ] Disable already-disabled → no-op or error
+- [ ] Enable not-disabled → no-op
+- [ ] Enable not-installed → error
+- [ ] Symlinks manually restored → enable detects and handles
+
+---
+
+## 15. Project-Local vs Global
+
+### Core functionality
+- [ ] Default is global (~/.pi/)
+- [ ] With `.pi/plugins.json` in cwd, uses project-local
+- [ ] `--global` forces global even with local config
+- [ ] Symlinks go to correct location per scope
+
+### Edge cases
+- [ ] Nested projects (parent and child have .pi/) → uses closest
+- [ ] Project-local install then run from parent dir → correct behavior
+- [ ] Same plugin installed globally and locally → local takes precedence?
+
+---
+
+## 16. Migration (`omp migrate`)
+
+### Core functionality
+- [ ] Detects legacy manifest.json
+- [ ] Converts to package.json format
+- [ ] Preserves all plugin info
+- [ ] Re-creates symlinks
+
+### Edge cases
+- [ ] No legacy manifest → "Nothing to migrate"
+- [ ] Partial migration (some plugins fail) → reports
+- [ ] Legacy plugin source gone → reports but continues
+- [ ] Backup of manifest.json created
+
+---
+
+## 17. Lock File
+
+### Core functionality
+- [ ] package-lock.json generated for global
+- [ ] plugins-lock.json generated for project-local
+- [ ] Reproducible installs with lock file
+
+### Edge cases
+- [ ] Lock file corrupt → regenerate with warning
+- [ ] Lock file deleted → works but warns about reproducibility
+
+---
+
+## 18. Symlinks Module
+
+### Core functionality
+- [ ] Creates symlinks correctly
+- [ ] Removes symlinks on uninstall
+- [ ] Validates symlink health
+
+### Edge cases
+- [ ] **BUG CHECK: Project-local uses correct base path (.pi/ not ~/.pi/)**
+- [ ] Destination is a directory → symlink whole directory
+- [ ] Destination is a file → symlink file
+- [ ] Parent directories created recursively
+- [ ] Windows compatibility (if applicable) → use junctions or requires admin
+
+---
+
+## 19. npm Module
+
+### Core functionality
+- [ ] npm install works with prefix
+- [ ] npm info fetches package data
+- [ ] npm search returns results
+- [ ] npm outdated parsed correctly
+
+### Edge cases
+- [ ] npm not installed → clear error
+- [ ] npm version too old → check and warn
+- [ ] Private registry → respects .npmrc
+- [ ] Scoped package with private registry → works
+
+---
+
+## 20. General Edge Cases
+
+### Error handling
+- [ ] All commands have try/catch at top level
+- [ ] Errors include actionable messages
+- [ ] Stack traces hidden unless DEBUG
+
+### Permissions
+- [ ] No sudo required for ~/.pi
+- [ ] Handles permission denied gracefully
+- [ ] Doesn't follow symlinks outside allowed paths (security)
+
+### Concurrency
+- [ ] Two `omp install` at once → lock file prevents corruption
+- [ ] Interrupted install → recoverable state
+
+### Unicode/i18n
+- [ ] Plugin names with unicode → handled
+- [ ] Paths with spaces → quoted correctly
+- [ ] Paths with unicode → work on all platforms
+
+---
+
+## Verification Steps
+
+For each section above:
+1. Read the relevant source file
+2. Trace the code path for the happy case
+3. Check each edge case is handled
+4. Note any missing error handling
+5. Run the command if possible to verify
+
+Report findings as:
+```
+## [Command Name]
+✓ Working: [list of working features]
+✗ Missing: [list of unimplemented features]
+⚠ Issues: [list of bugs or edge cases not handled]
+```

package/README.md

@@ -0,0 +1,224 @@
+# Oh My Pi (omp)
+
+Plugin manager for pi configuration. Like oh-my-zsh, but for pi.
+
+**v1.0 - npm-Native Architecture**
+
+Plugins are npm packages with an `omp` field in package.json. Discover plugins via npm, install with semver, and enjoy a familiar package management experience.
+
+## Installation
+
+```bash
+npm install -g @oh-my-pi/cli
+```
+
+## Quick Start
+
+```bash
+# Search for plugins
+omp search agents
+
+# Install a plugin
+omp install @oh-my-pi/subagents
+
+# List installed plugins
+omp list
+
+# Check for updates
+omp outdated
+
+# Update all plugins
+omp update
+```
+
+## Commands
+
+### Core Commands
+
+| Command              | Description                                            |
+|----------------------|--------------------------------------------------------|
+| `omp install [pkg...]` | Install plugin(s). No args = install from plugins.json |
+| `omp uninstall <pkg>`  | Remove plugin and its symlinks                         |
+| `omp update [pkg]`     | Update to latest within semver range                   |
+| `omp list`             | Show installed plugins                                 |
+| `omp link <path>`      | Symlink local plugin (dev mode)                        |
+
+### Discovery & Info
+
+| Command                | Description                                |
+|------------------------|--------------------------------------------|
+| `omp search <query>`   | Search npm for omp-plugin keyword          |
+| `omp info <pkg>`       | Show plugin details before install         |
+| `omp outdated`         | List plugins with newer versions           |
+
+### Maintenance
+
+| Command                  | Description                              |
+|--------------------------|------------------------------------------|
+| `omp init`               | Create .pi/plugins.json in current project |
+| `omp doctor`             | Check for broken symlinks, conflicts     |
+| `omp why <file>`         | Show which plugin installed a file       |
+| `omp enable/disable <pkg>` | Toggle plugin without uninstall        |
+
+### Plugin Development
+
+| Command            | Description                    |
+|--------------------|--------------------------------|
+| `omp create <name>`| Scaffold new plugin from template |
+| `omp link <path>`  | Symlink local plugin for dev   |
+
+### Flags
+
+- `--global / -g`: Install to ~/.pi (default)
+- `--save / -S`: Add to plugins.json
+- `--json`: Machine-readable output
+- `--force`: Overwrite conflicts
+
+## Plugin Format
+
+Plugins are npm packages with an `omp` field in package.json:
+
+```json
+{
+  "name": "@oh-my-pi/subagents",
+  "version": "1.0.0",
+  "description": "Task delegation agents for pi-agent",
+  "keywords": ["omp-plugin", "agents"],
+  "omp": {
+    "install": [
+      { "src": "agents/task.md", "dest": "agent/agents/task.md" },
+      { "src": "tools/task/", "dest": "agent/tools/task/" }
+    ]
+  },
+  "files": ["agents", "tools"]
+}
+```
+
+### Convention
+
+- Include `omp-plugin` keyword for discoverability
+- No namespace required (but `omp-` prefix is recommended)
+- Use semver for versioning
+
+## Directory Structure
+
+### Global (default)
+
+```
+~/.pi/
+├── plugins/
+│   ├── node_modules/          # npm-managed
+│   │   ├── @oh-my-pi/subagents/
+│   │   └── @oh-my-pi/metal-theme/
+│   ├── package.json           # Global plugin manifest
+│   └── package-lock.json      # Lock file
+├── agent/                     # Symlink targets
+│   ├── agents/
+│   ├── tools/
+│   ├── themes/
+│   └── commands/
+```
+
+### Project-Local
+
+```
+.pi/
+├── plugins.json               # Project plugin config
+├── plugins-lock.json          # Lock file
+└── node_modules/              # Project-scoped installs
+    └── omp-my-plugin/
+```
+
+Project plugins.json:
+```json
+{
+  "plugins": {
+    "@oh-my-pi/subagents": "^2.0.0",
+    "@oh-my-pi/metal-theme": "^1.0.0"
+  }
+}
+```
+
+## Install Flow
+
+```bash
+omp install @oh-my-pi/subagents
+```
+
+1. Resolve version from npm registry
+2. Check for conflicts (same dest from different plugins)
+3. `npm install --prefix ~/.pi/plugins omp-subagents`
+4. Read package.json → omp.install
+5. For each {src, dest}: symlink to ~/.pi/{dest}
+6. Recursively process dependencies with omp field
+7. Update package.json
+
+### Conflict Detection
+
+```
+⚠ Conflict: omp-dark-theme and omp-nord-theme both install agent/themes/dark.json
+  Choose: [1] dark-theme  [2] nord-theme  [3] abort
+```
+
+## Creating Plugins
+
+```bash
+omp create my-plugin
+```
+
+Creates:
+```
+omp-my-plugin/
+├── package.json
+├── README.md
+├── agents/
+│   └── example.md
+├── tools/
+├── themes/
+└── commands/
+```
+
+### Publishing
+
+1. Create a package with an `omp` field in package.json
+2. Add `omp-plugin` to keywords
+3. Publish to npm: `npm publish`
+4. Users install with: `omp install your-package-name`
+
+## Migration from v0.x
+
+If you have plugins installed with the old manifest.json format:
+
+```bash
+omp migrate
+```
+
+This will:
+1. Convert manifest.json → package.json format
+2. Move plugins to node_modules structure
+3. Re-create symlinks
+4. Archive old manifest.json
+
+## Bundled Example Plugins
+
+This package includes example plugins in the `plugins/` directory:
+
+- **@oh-my-pi/subagents** - Task delegation system with specialized subagents
+- **@oh-my-pi/metal-theme** - Metal theme for pi
+
+Install bundled plugins:
+```bash
+# After npm install -g @oh-my-pi/cli
+omp install $(npm root -g)/@oh-my-pi/cli/plugins/subagents
+omp install $(npm root -g)/@oh-my-pi/cli/plugins/metal-theme
+```
+
+Or link for development:
+```bash
+omp link ./plugins/subagents
+omp link ./plugins/metal-theme
+```
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,29 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.5/schema.json",
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"style": {
+				"noNonNullAssertion": "off",
+				"useConst": "error",
+				"useNodejsImportProtocol": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "off",
+				"noControlCharactersInRegex": "off",
+				"noEmptyInterface": "off"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"formatWithErrors": false,
+		"indentStyle": "tab",
+		"indentWidth": 3,
+		"lineWidth": 120
+	},
+	"files": {
+		"includes": ["src/**/*.ts", "!**/node_modules/**/*"]
+	}
+}