@oh-my-pi/cli 0.9.1 → 1.3.37

package/README.md

@@ -60,65 +60,74 @@ omp update
 
 ## How It Works
 
-omp installs plugins via npm and symlinks their files into your pi configuration directory:
+omp installs plugins globally via npm and sets up your pi configuration:
 
 ```
 ~/.pi/
-├── agent/              # Where plugin files get symlinked
-│   ├── agents/         # Agent definitions (.md)
-│   ├── commands/       # Slash commands (.md)
-│   ├── tools/          # Custom tools (.ts)
-│   └── themes/         # Theme files (.json)
-└── plugins/            # Plugin storage
-    ├── package.json    # Installed plugins manifest
-    └── node_modules/   # Actual plugin packages
+├── agent/                    # Pi's agent directory
+│   ├── agents/               # Agent definitions (.md) - symlinked
+│   ├── commands/             # Slash commands (.md) - symlinked
+│   ├── tools/omp/            # Tool loader
+│   │   └── index.ts          # Generated loader - imports tools from node_modules
+│   └── themes/               # Theme files (.json) - symlinked
+└── plugins/
+    ├── package.json          # Installed plugins manifest
+    ├── node_modules/         # Plugin packages (tools loaded directly from here)
+    └── store/                # Runtime configs (survives npm updates)
 ```
 
-Plugins declare which files to install via the `omp.install` field in their `package.json`. omp creates symlinks from the plugin's files into the appropriate `~/.pi/agent/` subdirectories.
+**Non-tool files** (agents, commands, themes) are symlinked via `omp.install` entries.
 
-## Global vs Local Plugins
+**Tools** are loaded directly from node_modules via a generated loader. Plugins specify `omp.tools` pointing to their tool factory. This allows tools to use npm dependencies without workarounds.
 
-omp supports both global and project-local plugin configurations:
+## Project-Level Overrides
 
-| Scope  | Config Location  | Agent Directory | Use Case                 |
-| ------ | ---------------- | --------------- | ------------------------ |
-| Global | `~/.pi/plugins/` | `~/.pi/agent/`  | Personal defaults        |
-| Local  | `.pi/`           | `.pi/agent/`    | Project-specific plugins |
+While plugins are installed globally, you can customize their behavior per-project using `.pi/overrides.json`:
 
 ```bash
-# Explicit scope
-omp install -g @oh-my-pi/subagents   # Global
-omp install -l @oh-my-pi/subagents   # Local
+# Initialize project overrides
+omp init
 
-# Auto-detect: uses local if .pi/plugins.json exists, otherwise global
-omp install @oh-my-pi/subagents
+# Disable a plugin for this project only
+omp disable @oh-my-pi/subagents -l
+
+# Enable different features in this project
+omp features @oh-my-pi/exa --set search -l
+
+# Override config variables for this project
+omp config @oh-my-pi/exa apiKey sk-project-specific -l
 ```
 
-Initialize a project-local config with `omp init`.
+Project overrides are stored in:
+
+- `.pi/overrides.json` - disabled plugins list
+- `.pi/store/` - feature and config overrides (merged with global, project takes precedence)
+
+The loader automatically merges project overrides at runtime.
 
 ## Commands
 
-| Command                | Alias | Description                                            |
-| ---------------------- | ----- | ------------------------------------------------------ |
-| `omp install [pkg...]` | `i`   | Install plugin(s). No args = install from plugins.json |
-| `omp uninstall <pkg>`  | `rm`  | Remove plugin and its symlinks                         |
-| `omp update [pkg]`     | `up`  | Update to latest within semver range                   |
-| `omp list`             | `ls`  | Show installed plugins                                 |
-| `omp search <query>`   |       | Search npm for plugins                                 |
-| `omp info <pkg>`       |       | Show plugin details before install                     |
-| `omp outdated`         |       | List plugins with newer versions                       |
-| `omp doctor`           |       | Check for broken symlinks, conflicts                   |
-| `omp link <path>`      |       | Symlink local plugin (dev mode)                        |
-| `omp create <name>`    |       | Scaffold new plugin from template                      |
-| `omp init`             |       | Create .pi/plugins.json in current project             |
-| `omp why <file>`       |       | Show which plugin installed a file                     |
-| `omp enable <name>`    |       | Enable a disabled plugin                               |
-| `omp disable <name>`   |       | Disable plugin without uninstalling                    |
-| `omp features <name>`  |       | List or configure plugin features                      |
-| `omp config <name>`    |       | Get or set plugin configuration variables              |
-| `omp env`              |       | Print environment variables for shell eval             |
-
-Most commands accept `-g`/`--global` or `-l`/`--local` flags to override scope auto-detection.
+| Command                | Alias | Description                                              |
+| ---------------------- | ----- | -------------------------------------------------------- |
+| `omp install [pkg...]` | `i`   | Install plugin(s). No args = install from package.json   |
+| `omp uninstall <pkg>`  | `rm`  | Remove plugin and its symlinks                           |
+| `omp update [pkg]`     | `up`  | Update to latest within semver range                     |
+| `omp list`             | `ls`  | Show installed plugins                                   |
+| `omp search <query>`   |       | Search npm for plugins                                   |
+| `omp info <pkg>`       |       | Show plugin details before install                       |
+| `omp outdated`         |       | List plugins with newer versions                         |
+| `omp doctor`           |       | Check for broken symlinks, conflicts                     |
+| `omp link <path>`      |       | Symlink local plugin (dev mode)                          |
+| `omp create <name>`    |       | Scaffold new plugin from template                        |
+| `omp init`             |       | Create .pi/overrides.json for project-local config       |
+| `omp why <file>`       |       | Show which plugin installed a file                       |
+| `omp enable <name>`    |       | Enable a disabled plugin (-l for project override)       |
+| `omp disable <name>`   |       | Disable plugin without uninstalling (-l for project)     |
+| `omp features <name>`  |       | List or configure plugin features (-l for project)       |
+| `omp config <name>`    |       | Get or set plugin configuration (-l for project)         |
+| `omp env`              |       | Print environment variables for shell eval (-l to merge) |
+
+Commands that modify plugin state (enable, disable, features, config, env) accept `-l`/`--local` to use project-level overrides instead of global config.
 
 ## Feature Selection
 
@@ -157,6 +166,9 @@ omp features @oh-my-pi/exa --disable search
 
 # Set exact feature list
 omp features @oh-my-pi/exa --set search,websets
+
+# Override features for current project only
+omp features @oh-my-pi/exa --set search -l
 ```
 
 ## Plugin Configuration
@@ -175,6 +187,9 @@ omp config @oh-my-pi/exa apiKey sk-xxx
 
 # Reset to default
 omp config @oh-my-pi/exa apiKey --delete
+
+# Override for current project only
+omp config @oh-my-pi/exa apiKey sk-project -l
 ```
 
 Variables with `env` mappings can be exported as environment variables:
@@ -186,6 +201,9 @@ eval "$(omp env)"
 # Fish shell
 omp env --fish | source
 
+# Merge project overrides
+eval "$(omp env -l)"
+
 # Persist in your shell config
 omp env >> ~/.bashrc
 ```
@@ -205,10 +223,31 @@ Plugins are npm packages with an `omp` field in `package.json`:
 			{ "src": "commands/research.md", "dest": "agent/commands/research.md" }
 		]
 	},
-	"files": ["agents", "commands", "tools", "themes"]
+	"files": ["agents", "commands"]
 }
 ```
 
+### Tools
+
+For plugins with custom tools, use the `tools` field instead of `install`:
+
+```json
+{
+	"name": "@oh-my-pi/my-tools",
+	"version": "1.0.0",
+	"keywords": ["omp-plugin"],
+	"omp": {
+		"tools": "tools"
+	},
+	"files": ["tools"],
+	"dependencies": {
+		"some-npm-package": "^1.0.0"
+	}
+}
+```
+
+The `tools` field points to a directory containing an `index.ts` that exports a tool factory. Tools are loaded directly from node_modules, so npm dependencies work normally.
+
 ### Features and Variables
 
 Plugins can define optional features and configurable variables:
@@ -219,7 +258,8 @@ Plugins can define optional features and configurable variables:
 	"version": "1.0.0",
 	"keywords": ["omp-plugin"],
 	"omp": {
-		"install": [{ "src": "tools/core.ts", "dest": "agent/tools/exa/core.ts" }],
+		"tools": "tools",
+		"runtime": "tools/runtime.json",
 		"variables": {
 			"apiKey": {
 				"type": "string",
@@ -231,13 +271,11 @@ Plugins can define optional features and configurable variables:
 		"features": {
 			"search": {
 				"description": "Web search capabilities",
-				"default": true,
-				"install": [{ "src": "tools/search.ts", "dest": "agent/tools/exa/search.ts" }]
+				"default": true
 			},
 			"websets": {
 				"description": "Curated content collections",
 				"default": false,
-				"install": [{ "src": "tools/websets.ts", "dest": "agent/tools/exa/websets.ts" }],
 				"variables": {
 					"defaultCollection": {
 						"type": "string",
@@ -250,6 +288,8 @@ Plugins can define optional features and configurable variables:
 }
 ```
 
+The `runtime` field points to a JSON file that the plugin imports to check feature state. omp stores user's feature selections in `~/.pi/plugins/store/` and injects them at load time, so they persist across npm updates.
+
 ### Plugin Structure
 
 ```
@@ -311,6 +351,9 @@ omp disable @oh-my-pi/subagents
 
 # Re-enable it later
 omp enable @oh-my-pi/subagents
+
+# Disable just for this project
+omp disable @oh-my-pi/subagents -l
 ```
 
 ## Credits