mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-17 04:02:21 +00:00
docs(coding-agent): remove duplicate packages content from extensions.md
Replace 130 lines of duplicate content with link to packages.md
This commit is contained in:
parent
930207130b
commit
d726c81faf
1 changed files with 1 additions and 134 deletions
|
|
@ -127,140 +127,7 @@ Additional paths via `settings.json`:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Use `pi install`, `pi remove`, `pi list`, and `pi update` to manage packages:
|
To share extensions via npm or git, see [packages.md](packages.md).
|
||||||
|
|
||||||
```bash
|
|
||||||
pi install npm:@foo/bar@1.0.0
|
|
||||||
pi install git:github.com/user/repo@v1
|
|
||||||
pi install https://github.com/user/repo # raw URLs work too
|
|
||||||
pi remove npm:@foo/bar
|
|
||||||
pi list # show installed packages
|
|
||||||
pi update # update all non-pinned packages
|
|
||||||
```
|
|
||||||
|
|
||||||
**Package filtering:** By default, packages load all resources (extensions, skills, prompts, themes). To selectively load only certain resources:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"packages": [
|
|
||||||
"npm:simple-pkg",
|
|
||||||
{
|
|
||||||
"source": "npm:shitty-extensions",
|
|
||||||
"extensions": ["extensions/oracle.ts", "extensions/memory-mode.ts"],
|
|
||||||
"skills": ["skills/a-nach-b"],
|
|
||||||
"themes": [],
|
|
||||||
"prompts": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- Omit a key to load all of that type from the package
|
|
||||||
- Use empty array `[]` to load none of that type
|
|
||||||
- Paths are relative to package root
|
|
||||||
- Use `!pattern` to exclude (e.g., `"themes": ["!funky.json"]`)
|
|
||||||
- Glob patterns supported via minimatch (e.g., `"extensions": ["**/*.ts", "!**/deprecated/*"]`)
|
|
||||||
- **Layered filtering:** User filters apply on top of manifest filters. If a manifest excludes 10 extensions and user adds one more exclusion, all 11 are excluded.
|
|
||||||
|
|
||||||
**Package deduplication:** If the same package appears in both global (`~/.pi/agent/settings.json`) and project (`.pi/settings.json`) settings, the project version wins and the global one is ignored. This prevents duplicate resource collisions when you have the same package installed at both scopes. Package identity is determined by:
|
|
||||||
- **npm packages:** Package name (e.g., `npm:foo` and `npm:foo@1.0.0` are the same identity)
|
|
||||||
- **git packages:** Repository URL without ref (e.g., `git:github.com/user/repo` and `git:github.com/user/repo@v1` are the same identity)
|
|
||||||
- **local paths:** Resolved absolute path
|
|
||||||
|
|
||||||
**Discovery rules:**
|
|
||||||
|
|
||||||
1. **Direct files:** `extensions/*.ts` or `*.js` → loaded directly
|
|
||||||
2. **Subdirectory with index:** `extensions/myext/index.ts` → loaded as single extension
|
|
||||||
3. **Subdirectory with package.json:** `extensions/myext/package.json` with `"pi"` field → loads declared paths
|
|
||||||
|
|
||||||
```
|
|
||||||
~/.pi/agent/extensions/
|
|
||||||
├── simple.ts # Direct file (auto-discovered)
|
|
||||||
├── my-tool/
|
|
||||||
│ └── index.ts # Subdirectory with index (auto-discovered)
|
|
||||||
└── my-extension-pack/
|
|
||||||
├── package.json # Declares multiple extensions
|
|
||||||
├── node_modules/ # Dependencies installed here
|
|
||||||
└── src/
|
|
||||||
├── safety-gates.ts # First extension
|
|
||||||
└── custom-tools.ts # Second extension
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
// my-extension-pack/package.json
|
|
||||||
{
|
|
||||||
"name": "my-extension-pack",
|
|
||||||
"dependencies": {
|
|
||||||
"zod": "^3.0.0"
|
|
||||||
},
|
|
||||||
"pi": {
|
|
||||||
"extensions": ["./src/safety-gates.ts", "./src/custom-tools.ts"],
|
|
||||||
"skills": ["./skills/"],
|
|
||||||
"prompts": ["./prompts/"],
|
|
||||||
"themes": ["./themes/dark.json"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The pi manifest supports glob patterns and exclusions:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"pi": {
|
|
||||||
"extensions": ["./extensions", "!**/deprecated/*"],
|
|
||||||
"skills": ["./skills", "!**/experimental/*"],
|
|
||||||
"themes": ["./themes/*.json"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Bundling other pi packages:**
|
|
||||||
|
|
||||||
To include resources from another pi package, add it as a dependency with `bundledDependencies` to ensure it's embedded in your published tarball:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "my-extension-pack",
|
|
||||||
"dependencies": {
|
|
||||||
"other-pi-package": "^1.0.0"
|
|
||||||
},
|
|
||||||
"bundledDependencies": [
|
|
||||||
"other-pi-package"
|
|
||||||
],
|
|
||||||
"pi": {
|
|
||||||
"extensions": [
|
|
||||||
"./extensions",
|
|
||||||
"./node_modules/other-pi-package/extensions",
|
|
||||||
"!**/unwanted-extension.ts"
|
|
||||||
],
|
|
||||||
"skills": [
|
|
||||||
"./skills",
|
|
||||||
"./node_modules/other-pi-package/skills"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`bundledDependencies` embeds the package inside your tarball, preserving the `node_modules/` structure. Without it, npm's hoisting could move the dependency elsewhere, breaking the paths.
|
|
||||||
|
|
||||||
**Discoverability:** Add the `pi-package` keyword to your `package.json` so users can find your package on npm:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "my-extension-pack",
|
|
||||||
"keywords": ["pi-package", "pi-extension", "..."],
|
|
||||||
...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Search for pi packages: `curl -s "https://registry.npmjs.org/-/v1/search?text=keywords:pi-package"`
|
|
||||||
|
|
||||||
The `package.json` approach enables:
|
|
||||||
- Multiple extensions from one package
|
|
||||||
- Skills, prompts, and themes declared alongside extensions
|
|
||||||
- Third-party npm dependencies (resolved via jiti)
|
|
||||||
- Nested source structure (no depth limit within the package)
|
|
||||||
- Deployment to and installation from npm
|
|
||||||
|
|
||||||
## Available Imports
|
## Available Imports
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue