@x-otto/install 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,78 @@
+# @x-otto/install
+
+> Universal installation engine for otto skills, plugins, and MCP servers.
+
+`@x-otto/install` is the single entry point for adding any type of capability to an otto workspace — whether from a local archive, npm registry, git repository, or HTTP URL. It handles source resolution, content-type detection, atomic installation, post-install hooks, and version upgrades, with built-in security gates against archive bombs and path traversal attacks.
+
+## Installation
+
+```bash
+pnpm add @x-otto/install
+```
+
+## Usage
+
+```typescript
+import { InstallManager } from '@x-otto/install'
+
+const manager = new InstallManager()
+
+// Install a skill from a local .tgz archive
+const result = await manager.install('./my-skill.tgz', {
+  workspaceDir: '/path/to/project',
+  onProgress: (p) => console.log(`[${p.phase}] ${p.message}`),
+})
+
+// Install a plugin from npm
+const pluginResult = await manager.install('@scope/my-plugin', {
+  global: true,
+})
+
+// Install an MCP server from a git repo tag
+const mcpResult = await manager.install('https://github.com/user/mcp-server.git', {
+  ref: 'v1.2.0',
+  env: { API_KEY: 'xxx' },
+})
+```
+
+The `InstallManager` auto-detects the source type (file/url/git/npm) and content type (skill/plugin/mcp). Use `--as` to override auto-detection:
+
+```typescript
+// Force treat content as plugin even if auto-detect might guess skill
+await manager.install('./dir', { as: 'plugin' })
+```
+
+## Key Exports
+
+### Installation
+- `InstallManager` — Top-level orchestrator with `install()` and `installSkill()` methods
+- `InstallOptions` — Workspace, scope, force, dry-run, sub-path, ref, progress callbacks
+- `InstallResult` — Success status, target path, definition/manifest, warnings, pending capabilities
+
+### Uninstallation
+- `uninstall()` — Remove skill/plugin/mcp by name
+- `detectUninstallTarget()` — Determine installed type from name
+- `listInstalledItems()` — Enumerate all installed items across scopes
+
+### Upgrades
+- `scanInstalledVersions()` — Collect version info from installed items
+- `checkUpgrades()` — Check npm/git remote for newer versions
+- `checkGitUpgrades()` — Git-specific `ls-remote` comparison
+
+### Utilities
+- `extractArchive()` / `createArchive()` — `.tar.gz`/`.tar`/`.zip` extraction and packaging
+- `validateExtractedPaths()` / `checkArchiveBomb()` — Security validation (traversal, bomb, size)
+- `sanitizeSourceUrl()` — Strip credentials from stored URLs
+
+### Registry Discovery
+- `RegistryClient` — Multi-source registry index fetch/cache/aggregation (RFC-201)
+- `parseRegistry()` — Zod-validated registry JSON parsing with fail-soft per-entry handling
+
+## Dependencies
+
+- **Internal**: `@x-otto/mcp`, `@x-otto/plugin`, `@x-otto/skill`, `@x-otto/shared`
+- **External**: `zod`, Node.js built-ins (fs, path, os, child_process)
+
+## Related
+
+- [Architecture](./ARCHITECTURE.md)