mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 13:03:42 +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:
|
||||
|
||||
```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
|
||||
To share extensions via npm or git, see [packages.md](packages.md).
|
||||
|
||||
## Available Imports
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue