feat(plugins): add --from flag to load plugin command (#5)

* feat(plugins): add --from flag to load plugin command

- Add --from flag to load plugins from any URL (npm, file://, https://, git://)
- Enforce exclusive usage of package name vs --from flag
- Update help text and documentation with new functionality
- Add examples for loading plugins from various sources
- Adhere to npm standards by wrapping npm install directly

Commands are now mutually exclusive:
- c8 load plugin <name>        (from npm registry)
- c8 load plugin --from <url>  (from any valid URL)

Refs: Plugin system enhancement

* refactor(plugins): remove metadata export requirement

- Plugins now only need to export commands object
- Remove metadata validation from listPlugins
- Simplify plugin detection to check for c8ctl-plugin.js/ts file
- Update all tests to remove metadata checks
- Update documentation and examples

This simplifies plugin development by removing unnecessary boilerplate.

Author: vobu

EXAMPLES.md

@@ -357,9 +357,14 @@ c8 output text
 ### Load Plugin
 
 ```bash
-# Install a c8ctl plugin from npm
+# Install a c8ctl plugin from npm registry
 c8 load plugin my-custom-plugin
 
+# Install a plugin from a URL (file, https, git, etc.)
+c8 load plugin --from https://github.com/user/my-plugin
+c8 load plugin --from file:///path/to/local/plugin
+c8 load plugin --from git://github.com/user/plugin.git
+
 # The plugin is now available
 # (assuming the plugin exports an 'analyze' command)
 c8 analyze
@@ -381,7 +386,7 @@ c8 list plugins
 
 **Plugin Development:**
 
-Plugins should include a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file that exports custom commands. The `c8ctl` runtime object provides environment information:
+Plugins must be regular Node.js modules with a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory. The plugin file must export a `commands` object. The `c8ctl` runtime object provides environment information:
 
 ```typescript
 // c8ctl-plugin.ts

README.md

@@ -124,9 +124,15 @@ c8 output text
 c8ctl supports a plugin system that allows extending the CLI with custom commands via npm packages.
 
 ```bash
-# Load a plugin (wraps npm install)
+# Load a plugin from npm registry
 c8 load plugin <package-name>
 
+# Load a plugin from a URL (including file URLs)
+c8 load plugin --from <url>
+c8 load plugin --from file:///path/to/plugin
+c8 load plugin --from https://github.com/user/repo
+c8 load plugin --from git://github.com/user/repo.git
+
 # Unload a plugin (wraps npm uninstall)
 c8 unload plugin <package-name>
 
@@ -135,8 +141,9 @@ c8 list plugins
 ```
 
 **Plugin Requirements:**
-- Plugin packages must include a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file
-- The plugin file should export custom commands
+- Plugin packages must be regular Node.js modules
+- They must include a `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in the root directory
+- The plugin file must export a `commands` object
 - Plugins are installed in `node_modules` like regular npm packages
 - The runtime object `c8ctl` provides environment information to plugins
 

src/commands/help.ts

@@ -52,14 +52,16 @@ Commands:
   run       <path>           Deploy and start process
   add       profile <name>   Add a profile
   remove    profile <name>   Remove a profile (alias: rm)
-  load      plugin <name>    Load a c8ctl plugin (npm install wrapper)
+  load      plugin <name>    Load a c8ctl plugin from npm registry
+  load      plugin --from    Load a c8ctl plugin from URL (file://, https://, git://)
   unload    plugin <name>    Unload a c8ctl plugin (npm uninstall wrapper)
   use       profile|tenant   Set active profile or tenant
   output    json|text        Set output format
   help                       Show this help
 
 Flags:
   --profile <name>  Use specific profile for this command
+  --from <url>      Load plugin from URL (use with 'load plugin')
   --version, -v     Show version
   --help, -h        Show help
 
@@ -77,6 +79,8 @@ Examples:
   c8 run ./my-process.bpmn        Deploy and start process
   c8 use profile prod             Set active profile
   c8 output json                  Switch to JSON output
+  c8 load plugin my-plugin        Load plugin from npm registry
+  c8 load plugin --from file:///path/to/plugin  Load plugin from file URL
 `.trim());
 }
 

src/commands/plugins.ts

@@ -4,24 +4,39 @@
 
 import { getLogger } from '../logger.ts';
 import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
  * Load a plugin (npm install wrapper)
+ * Supports either package name or --from flag with URL
  */
-export function loadPlugin(packageName: string): void {
+export function loadPlugin(packageNameOrFrom?: string, fromUrl?: string): void {
   const logger = getLogger();
 
-  if (!packageName) {
-    logger.error('Package name required. Usage: c8 load plugin <package-name>');
+  // Validate exclusive usage
+  if (packageNameOrFrom && fromUrl) {
+    logger.error('Cannot specify both package name and --from flag. Use either "c8 load plugin <name>" or "c8 load plugin --from <url>"');
+    process.exit(1);
+  }
+  
+  if (!packageNameOrFrom && !fromUrl) {
+    logger.error('Package name or --from URL required. Usage: c8 load plugin <package-name> OR c8 load plugin --from <url>');
     process.exit(1);
   }
 
   try {
-    logger.info(`Loading plugin: ${packageName}...`);
-    execSync(`npm install ${packageName}`, { stdio: 'inherit' });
-    logger.success('Plugin loaded successfully', packageName);
+    if (fromUrl) {
+      // Install from URL (file://, https://, git://, etc.)
+      logger.info(`Loading plugin from: ${fromUrl}...`);
+      execSync(`npm install ${fromUrl}`, { stdio: 'inherit' });
+      logger.success('Plugin loaded successfully from URL', fromUrl);
+    } else {
+      // Install from npm registry by package name
+      logger.info(`Loading plugin: ${packageNameOrFrom}...`);
+      execSync(`npm install ${packageNameOrFrom}`, { stdio: 'inherit' });
+      logger.success('Plugin loaded successfully', packageNameOrFrom);
+    }
   } catch (error) {
     logger.error('Failed to load plugin', error as Error);
     process.exit(1);
@@ -70,16 +85,13 @@ export function listPlugins(): void {
     for (const [name, version] of Object.entries(allDeps)) {
       try {
         // Try to resolve the package
-        const packagePath = join(process.cwd(), 'node_modules', name, 'package.json');
-        const pkgJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+        const packageDir = join(process.cwd(), 'node_modules', name);
 
-        // Check if package exports c8ctl-plugin.js or c8ctl-plugin.ts
-        const hasPlugin = pkgJson.main === 'c8ctl-plugin.js' || 
-                         pkgJson.main === 'c8ctl-plugin.ts' ||
-                         pkgJson.exports?.['./c8ctl-plugin.js'] ||
-                         pkgJson.exports?.['./c8ctl-plugin.ts'];
+        // Check if package has c8ctl-plugin.js or c8ctl-plugin.ts file in root
+        const hasPluginFile = existsSync(join(packageDir, 'c8ctl-plugin.js')) ||
+                             existsSync(join(packageDir, 'c8ctl-plugin.ts'));
 
-        if (hasPlugin) {
+        if (hasPluginFile) {
           plugins.push({
             Name: name,
             Version: version as string,

src/index.ts

@@ -73,6 +73,7 @@ function parseCliArgs() {
         oAuthUrl: { type: 'string' },
         defaultTenantId: { type: 'string' },
         version_num: { type: 'string' },
+        from: { type: 'string' },
       },
       allowPositionals: true,
       strict: false,
@@ -192,11 +193,21 @@ async function main() {
   }
 
   if (verb === 'load' && normalizedResource === 'plugin') {
-    if (!args[0]) {
-      logger.error('Package name required. Usage: c8 load plugin <package-name>');
+    const fromUrl = values.from as string | undefined;
+    const packageName = args[0];
+    
+    // Ensure exclusive usage
+    if (packageName && fromUrl) {
+      logger.error('Cannot specify both package name and --from flag. Use either "c8 load plugin <name>" or "c8 load plugin --from <url>"');
+      process.exit(1);
+    }
+    
+    if (!packageName && !fromUrl) {
+      logger.error('Package name or --from URL required. Usage: c8 load plugin <package-name> OR c8 load plugin --from <url>');
       process.exit(1);
     }
-    loadPlugin(args[0]);
+    
+    loadPlugin(packageName, fromUrl);
     return;
   }
 

tests/fixtures/plugins/README.md

@@ -10,7 +10,6 @@ TypeScript implementation demonstrating:
 - TypeScript type annotations
 - Access to c8ctl runtime object
 - Multiple command exports (analyze, validate)
-- Metadata export
 
 **Usage in plugins:**
 ```typescript
@@ -29,7 +28,6 @@ JavaScript implementation demonstrating:
 - Command with hyphens ('deploy-all')
 - Argument handling
 - Multiple commands (deploy-all, status, report)
-- Metadata with command list
 
 **Usage in plugins:**
 ```javascript
@@ -44,16 +42,15 @@ export const commands = {
 
 For a package to be recognized as a c8ctl plugin:
 
-1. Must have either `c8ctl-plugin.js` or `c8ctl-plugin.ts` as main entry
-2. Must export a `commands` object with async functions
-3. Should export `metadata` with name, version, description
+1. Must be a regular Node.js module with proper package.json
+2. Must have either `c8ctl-plugin.js` or `c8ctl-plugin.ts` file in root directory
+3. Must export a `commands` object with async functions
 4. Can access c8ctl runtime via `import { c8ctl } from 'c8ctl/runtime'`
 
 ## Testing
 
 These fixtures are used by `tests/unit/plugins.test.ts` to verify:
 - Plugin structure validation
 - Command export format
-- Metadata format
 - Dynamic import capability
 - Runtime object access

tests/fixtures/plugins/c8ctl-plugin.js

@@ -37,10 +37,3 @@ export const commands = {
     console.log(`Output format: ${format}`);
   },
 };
-
-export const metadata = {
-  name: 'sample-js-plugin',
-  version: '2.0.0',
-  description: 'A sample JavaScript plugin for c8ctl',
-  commands: ['deploy-all', 'status', 'report'],
-};

tests/fixtures/plugins/c8ctl-plugin.ts

@@ -29,9 +29,3 @@ export const commands = {
     console.log(`Validating files: ${args.join(', ')}`);
   },
 };
-
-export const metadata = {
-  name: 'sample-ts-plugin',
-  version: '1.0.0',
-  description: 'A sample TypeScript plugin for c8ctl',
-};

tests/unit/plugins.test.ts

@@ -55,17 +55,6 @@ describe('Plugin Structure', () => {
       assert.ok(pluginContent.includes('c8ctl.env'), 'Plugin uses c8ctl.env');
     });
 
-    test('should have metadata export', async () => {
-      const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.ts');
-      const pluginContent = readFileSync(pluginPath, 'utf-8');
-      
-      // Verify plugin exports metadata
-      assert.ok(pluginContent.includes('export const metadata'), 'Plugin exports metadata');
-      assert.ok(pluginContent.includes('name:'), 'Metadata has name');
-      assert.ok(pluginContent.includes('version:'), 'Metadata has version');
-      assert.ok(pluginContent.includes('description:'), 'Metadata has description');
-    });
-
     test('should be valid TypeScript syntax', async () => {
       const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.ts');
       const pluginContent = readFileSync(pluginPath, 'utf-8');
@@ -90,17 +79,6 @@ describe('Plugin Structure', () => {
       assert.ok(pluginContent.includes('report:'), 'Plugin has report command');
     });
 
-    test('should have metadata export', async () => {
-      const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.js');
-      const pluginContent = readFileSync(pluginPath, 'utf-8');
-      
-      // Verify plugin exports metadata
-      assert.ok(pluginContent.includes('export const metadata'), 'Plugin exports metadata');
-      assert.ok(pluginContent.includes('name:'), 'Metadata has name');
-      assert.ok(pluginContent.includes('version:'), 'Metadata has version');
-      assert.ok(pluginContent.includes('commands:'), 'Metadata lists commands');
-    });
-
     test('should use ES6 module syntax', async () => {
       const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.js');
       const pluginContent = readFileSync(pluginPath, 'utf-8');
@@ -130,7 +108,6 @@ describe('Plugin Structure', () => {
         assert.ok(plugin.commands, 'Plugin has commands export');
         assert.ok(typeof plugin.commands.analyze === 'function', 'analyze is a function');
         assert.ok(typeof plugin.commands.validate === 'function', 'validate is a function');
-        assert.ok(plugin.metadata, 'Plugin has metadata export');
       } catch (error) {
         // If import fails, just verify the file exists
         const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.ts');
@@ -149,7 +126,6 @@ describe('Plugin Structure', () => {
         assert.ok(typeof plugin.commands['deploy-all'] === 'function', 'deploy-all is a function');
         assert.ok(typeof plugin.commands.status === 'function', 'status is a function');
         assert.ok(typeof plugin.commands.report === 'function', 'report is a function');
-        assert.ok(plugin.metadata, 'Plugin has metadata export');
       } catch (error) {
         // If import fails, just verify the file exists
         const pluginPath = join(process.cwd(), 'tests/fixtures/plugins/c8ctl-plugin.js');