opkg 0.8.3 → 0.8.5

package/README.md

@@ -9,7 +9,7 @@
   </a>
 </p>
 
-<p align="center">Universal plugins for coding agents.</p>
+<p align="center">The package manager for coding agent configs.</p>
 <p align="center">
 <a href="https://www.npmjs.com/package/opkg " target="blank">
   <img src="https://img.shields.io/npm/v/opkg?style=flat-square" alt="Npm package for OpenPackage">
@@ -33,8 +33,7 @@ OpenPackage enables simple, modular management of coding agent configs, providin
 
 ## Why OpenPackage?
 
-Modern AI coding tools are powerful and efficient when rules, commands, subagents, and skills are properly setup.  
-Unfortunately, these files remain difficult to organize and manage.  
+Modern AI coding tools are powerful and efficient when rules, commands, subagents, and skills are properly setup. Unfortunately, these files remain difficult to organize and manage.  
 
 OpenPackage provides a centralized and universal interface for installing, uninstalling, and packaging coding agent config files for simplified management and distribution.
 
@@ -54,7 +53,7 @@ OpenPackage provides a centralized and universal interface for installing, unins
 
 At its core, OpenPackage is a lightweight CLI package manager that performs installs and uninstalls of config files, with the ability to keep track of file sources and dependencies, plus packaging capabilities.
 
-It's basically a much more powerful, universal, and open source version of Claude Code Plugins.
+It's basically a much more powerful, universal, and open source version of Vercel Skills and Claude Code Plugins.
 
 ## Install OpenPackage
 
@@ -75,44 +74,61 @@ Installs all files from a specified resource into the codebase at cwd, formatted
 #### Install resources (packages, plugins, rules, commands, agents, and skills)
 
 ```bash title="Terminal"
-# Packages or Marketplaces
-opkg install gh@<user>/<repo>
+# OpenPackage local or remote packages
+opkg install <package-name>
 
-# Packages or Claude Plugins hosted on GitHub
-opkg install gh@<user>/<repo> --plugins <plugin-name>
-
-# Agents and Skills hosted on GitHub
-opkg install gh@<user>/<repo> --plugins <plugin-name> --agents <agent-name>
-opkg install gh@<user>/<repo> --plugins <plugin-name> --skills <agent-name>
-opkg install gh@<user>/<repo> --skills <agent-name>
+# Github repos
+opkg install gh@<owner>/<repo>
 
 # GitHub URLs
-opkg install https://github.com/<user>/<repo>/<path-to-resource>
+opkg install https://github.com/<owner>/<repo>/<path-to-resource>
 
 # Local path to package or Claude Plugin
 opkg install <path-to-dir>
 
+# Git URLs
+opkg install git@<host>:<repo>.git
+
 # Examples
+opkg install essentials
 opkg install gh@anthropics/claude-code --plugins code-review
+opkg install gh@wshobson/agents --plugins ui-design --agents ui-designer
+opkg install gh@wshobson/agents/plugins/ui-design/agents/ui-designer
 opkg install gh@vercel-labs/agent-skills --skills react-best-practices
 opkg install https://github.com/anthropics/claude-code/tree/main/plugins/code-review
+opkg install https://github.com/wshobson/agents/tree/main/plugins/ui-design/ui-designer.md
 opkg install https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
 ```  
 
 #### Options
 
-Use the `--global` (or `-g`) option to install files to user scope:
-```bash title="Terminal"
-# Installs to home dir, ex: ~/.cursor/, ~/.opencode/
-opkg install github:anthropics/claude-code -g
-```  
+| Option | Description |
+| --- | --- |
+| `-g, --global`               | Install to user directory instead of project |
+| `-a, --agents <agents...>`   | Install specific agents by name |
+| `-s, --skills <skills...>`   | Install specific skills by name |
+| `--plugins <plugins...>`     | Install specific plugins by name |
+| `--platforms`                | Install to only specified platforms |
+| `--remote`                   | Install from remote source / skip cache |
 
 ### List installed resources
 ```bash title="Terminal"
 opkg list             # Lists resources installed to workspace at cwd
 opkg list <package>   # Lists installed files for specified resource
 ```  
-Use the status command to show an overview of packages and files installed.
+Use the list command to show an overview of packages and files installed.
+
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `-p, --project`              | Lists only project scoped packages & resource file count |
+| `-g, --global`               | Lists only user scoped packages & resource file count |
+| `-a, --all`                  | Lists all packages recursively (includes nested) |
+| `-f, --files`                | Lists all resource files |
+| `-t, --tracked`              | Lists all packages & resources tracked by OpenPackage |
+| `-u, --untracked`            | Lists all resources not tracked by OpenPackage |
+| `--platforms`                | Lists packages & files from specified platforms |
 
 ### Uninstall packages
 ```bash title="Terminal"
@@ -120,6 +136,12 @@ opkg uninstall <package>
 ```  
 Removes all files for a package from the codebase at cwd.
 
+#### Options
+
+| Option | Description |
+| --- | --- |
+| `-g, --global`               | Uninstall from user directory |
+
 > [!TIP]  
 > Learn more by heading over to the [official docs](https://openpackage.dev/docs).
 
@@ -161,7 +183,7 @@ opkg remove <package> commands/clean.md         # Removes file or dir from packa
 > [!TIP]  
 > Learn more about packages from the [packages doc](https://openpackage.dev/docs/packages) on our official docs.
 
-## Supported Platforms
+## Supported Platforms & Files
 
 OpenPackage performs installation and platform sync of files for supported AI coding platforms outlined by the table below.  
 

package/dist/commands/install.js

@@ -2,6 +2,8 @@ import { withErrorHandling } from '../utils/errors.js';
 import { createOrchestrator } from '../core/install/orchestrator/index.js';
 import { normalizeInstallOptions } from '../core/install/preprocessing/index.js';
 import { createExecutionContext } from '../core/execution-context.js';
+import { createTelemetryCollector } from '../utils/telemetry.js';
+import { createHttpClient } from '../utils/http-client.js';
 /**
  * Setup install command
  */
@@ -10,34 +12,60 @@ export function setupInstallCommand(program) {
         .command('install')
         .alias('i')
         .description('Install packages to workspace')
-        .argument('[package-name]', 'name of the package to install (optional - installs workspace-level files and all packages from openpackage.yml if not specified). ' +
-        'Supports package@version syntax.')
+        .argument('[resource-spec]', 'resource to install (package[@version], gh@owner/repo, https://github.com/owner/repo, /path/to/local, or git@host:repo.git)')
         .option('-g, --global', 'install to home directory (~/) instead of current workspace')
+        .option('-a, --agents <names...>', 'install specific agents by name (matches frontmatter name or filename)')
+        .option('-s, --skills <names...>', 'install specific skills by name (matches SKILL.md frontmatter name or directory name)')
+        .option('-r, --rules <names...>', 'install specific rules by name (matches frontmatter name or filename)')
+        .option('-c, --commands <names...>', 'install specific commands by name (matches frontmatter name or filename)')
+        .option('--plugins <names...>', 'install specific plugins from marketplace (bypasses interactive selection)')
+        .option('--platforms <platforms...>', 'install to specific platforms (e.g., cursor claudecode opencode)')
         .option('--dry-run', 'preview changes without applying them')
         .option('--force', 'overwrite existing files')
         .option('--conflicts <strategy>', 'conflict handling strategy: keep-both, overwrite, skip, or ask')
-        .option('--dev', 'add package to dev-dependencies instead of dependencies')
-        .option('--platforms <platforms...>', 'prepare specific platforms (e.g., cursor claudecode opencode)')
+        .option('--dev', 'add resource to dev-dependencies (instead of dependencies)')
         .option('--remote', 'pull and install from remote registry, ignoring local versions')
         .option('--local', 'resolve and install using only local registry versions, skipping remote metadata and pulls')
         .option('--profile <profile>', 'profile to use for authentication')
         .option('--api-key <key>', 'API key for authentication (overrides profile)')
-        .option('--plugins <names...>', 'install specific plugins from marketplace (bypasses interactive selection)')
-        .option('--agents <names...>', 'install specific agents by name (matches frontmatter name or filename)')
-        .option('--skills <names...>', 'install specific skills by name (matches SKILL.md frontmatter name or directory name)')
+        // .option('--list', 'interactively select resources to install (agents, skills, commands, etc.)')
         .action(withErrorHandling(async (packageName, options, command) => {
+        // Validate mutually exclusive options
+        if (options.list && (options.agents || options.skills || options.rules || options.commands)) {
+            throw new Error('--list cannot be used with --agents, --skills, --rules, or --commands. Use --list for interactive selection or specify filters directly.');
+        }
         // Get program-level options (for --cwd)
         const programOpts = command.parent?.opts() || {};
-        // Create execution context
+        // Create telemetry collector
+        const telemetryCollector = await createTelemetryCollector('install');
+        // Create execution context with telemetry
         const execContext = await createExecutionContext({
             global: options.global,
             cwd: programOpts.cwd
         });
+        // Add telemetry collector to context
+        if (telemetryCollector) {
+            execContext.telemetryCollector = telemetryCollector;
+        }
         // Normalize all options at CLI boundary
         const normalizedOptions = normalizeInstallOptions(options);
         // Create and execute orchestrator with execution context
         const orchestrator = createOrchestrator();
         const result = await orchestrator.execute(packageName, normalizedOptions, execContext);
+        // Flush telemetry (truly fire-and-forget, non-blocking)
+        if (telemetryCollector && result.success) {
+            // Run in background without blocking command completion
+            setImmediate(() => {
+                createHttpClient({
+                    apiKey: options.apiKey,
+                    profile: options.profile
+                })
+                    .then(httpClient => telemetryCollector.flush(httpClient))
+                    .catch(() => {
+                    // Silent failure - already logged in telemetry module
+                });
+            });
+        }
         // Handle result
         if (!result.success) {
             if (result.error === 'Package not found') {

package/dist/commands/install.js.map

@@ -1 +1 @@
-{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,KAAK,CAAC,GAAG,CAAC;SACV,WAAW,CAAC,+BAA+B,CAAC;SAC5C,QAAQ,CACP,gBAAgB,EAChB,qIAAqI;QACrI,kCAAkC,CACnC;SACA,MAAM,CAAC,cAAc,EAAE,6DAA6D,CAAC;SACrF,MAAM,CAAC,WAAW,EAAE,uCAAuC,CAAC;SAC5D,MAAM,CAAC,SAAS,EAAE,0BAA0B,CAAC;SAC7C,MAAM,CAAC,wBAAwB,EAAE,gEAAgE,CAAC;SAClG,MAAM,CAAC,OAAO,EAAE,yDAAyD,CAAC;SAC1E,MAAM,CAAC,4BAA4B,EAAE,+DAA+D,CAAC;SACrG,MAAM,CAAC,UAAU,EAAE,gEAAgE,CAAC;SACpF,MAAM,CAAC,SAAS,EAAE,4FAA4F,CAAC;SAC/G,MAAM,CAAC,qBAAqB,EAAE,mCAAmC,CAAC;SAClE,MAAM,CAAC,iBAAiB,EAAE,gDAAgD,CAAC;SAC3E,MAAM,CAAC,sBAAsB,EAAE,4EAA4E,CAAC;SAC5G,MAAM,CAAC,qBAAqB,EAAE,wEAAwE,CAAC;SACvG,MAAM,CAAC,qBAAqB,EAAE,uFAAuF,CAAC;SACtH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAC7B,WAA+B,EAC/B,OAIC,EACD,OAAgB,EAChB,EAAE;QACF,wCAAwC;QACxC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAEjD,2BAA2B;QAC3B,MAAM,WAAW,GAAG,MAAM,sBAAsB,CAAC;YAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,EAAE,WAAW,CAAC,GAAG;SACrB,CAAC,CAAC;QAEH,wCAAwC;QACxC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;QAE3D,yDAAyD;QACzD,MAAM,YAAY,GAAG,kBAAkB,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,iBAAiB,EAAE,WAAW,CAAC,CAAC;QAEvF,gBAAgB;QAChB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,KAAK,mBAAmB,EAAE,CAAC;gBACzC,OAAO,CAAC,4BAA4B;YACtC,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,+BAA+B,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC,CAAC,CAAC;AACR,CAAC"}
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/commands/install.ts"],"names":[],"mappings":"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"}