Package Management
Relevant source files
The following files were used as context for generating this wiki page:
Package Management in OCX refers to the systematic process of discovering, installing, updating, and verifying AI components and npm plugins within the OpenCode ecosystem. It follows a "Copy. Paste. Own." philosophy where components are fetched from registries and integrated directly into a project's .opencode/ directory, ensuring users have full ownership and auditability of the code.
Sources: README.md:9-12, examples/registry-starter/AGENTS.md:5-9
Core Architecture
The package management system is built around a unified CLI that interacts with a central lockfile (ocx.lock) and project configuration (opencode.jsonc). It supports two primary types of "packages": registry-based components (skills, agents, plugins, bundles) and standard npm plugins.
Data Flow for Component Installation
The following diagram illustrates the lifecycle of a component installation from a registry to the local project.
The installation process prioritizes "Elegant Defense" by performing pre-flight conflict detection before writing any files to disk.
Sources: packages/cli/src/commands/add.ts:133-149, packages/cli/src/commands/add.ts:311-340, README.md:46-51
Components and Registries
OCX manages four distinct component types, each serving a specific role in AI assistant behavior or system functionality.
| Type | Purpose | File Format |
|---|---|---|
ocx:skill | Instructions for AI behavior | Markdown (SKILL.md) |
ocx:plugin | Code extending OpenCode (hooks/tools) | TypeScript (.ts) |
ocx:agent | Specialized AI role definitions | Markdown (.md) |
ocx:bundle | Collection of related components | JSON manifest |
Sources: examples/registry-starter/AGENTS.md:105-110
Registry Manifest
Every registry must contain a registry.jsonc file that defines its namespace, versioning, and the list of available components. Components are identified by a qualified name in the format namespace/component-name.
Sources: CONTRIBUTING.md:21-48, examples/registry-starter/AGENTS.md:83-100
Installation Logic
The add command acts as the primary entry point for bringing new functionality into a project. It implements a multi-phase installation strategy to ensure project integrity.
Phase 1: Input Parsing and Routing
The system uses a discriminated union to route inputs between npm plugins and registry components.
- npm plugins: Validates the package exists on the npm registry and checks if it follows OpenCode plugin conventions (ESM modules).
- Registry components: Resolves the full dependency graph and fetches file manifests.
Sources: packages/cli/src/commands/add.ts:46-77, packages/cli/src/commands/add.ts:175-195
Phase 2: Integrity and Conflict Resolution
Before writing files, the system:
- Hashes Bundles: Computes a SHA-256 hash of all incoming files.
- Verifies Locks: Compares computed hashes against
ocx.lockif the component was previously installed. - Detects Conflicts: Checks if target paths are already occupied by files from different components or if existing files have been modified locally.
// Sources: packages/cli/src/commands/add.ts:347-366
// Layer 2 path safety: Verify all target paths are inside cwd
for (const file of component.files) {
const targetPath = join(cwd, resolveTargetPath(file.target, !!options.global))
assertPathInside(targetPath, cwd)
}
Update and Audit System
OCX provides tools to maintain packages and audit changes from upstream registries.
Update Workflow
The update command allows users to sync local components with registry changes. It supports version pinning using the @version syntax (e.g., kdco/agents@1.2.0).
Lockfile Structure
The ocx.lock file is auto-generated to track the state of installed components. It ensures deterministic builds and guards against tampering.
| Field | Description |
|---|---|
registry | The source namespace of the component |
version | The semantic version installed |
hash | SHA-256 integrity hash of the component bundle |
files | List of local file paths managed by the component |
installedAt | ISO timestamp of initial installation |
Sources: packages/cli/src/commands/add.ts:446-455, README.md:195-200
Configuration Merging
A key feature of OCX package management is the automatic merging of component configurations into opencode.jsonc. Components can inject:
- MCP Servers: Remote or local Model Context Protocol servers.
- Tools: Enabled or disabled patterns for AI tools.
- Plugins: npm package references.
- Permissions: Scoped access for bash and filesystem operations.
Sources: examples/registry-starter/AGENTS.md:204-245, README.md:100-112
Summary
Package management in OCX is designed for reliability and user control. By combining SHA-256 integrity verification, atomic installation phases, and a ShadCN-inspired local ownership model, it provides a robust infrastructure for extending AI capabilities without sacrificing the maintainability of the underlying software project.
Sources: README.md:85-93, AGENTS.md:13-17