@lsst/pik 0.5.2 → 0.5.3

package/README.md

@@ -8,7 +8,29 @@ A developer toolkit with extensible plugins for common development tasks.
 npm install -g @lsst/pik
 ```
 
-## Plugins
+## Configuration
+
+Create `pik.config.ts` in your project root:
+
+```typescript
+export default {
+  // Enable select plugin
+  select: {
+    include: ['src/**/*.ts', '.env'],
+  },
+
+  // Enable worktree plugin
+  worktree: {
+    baseDir: '../',
+    copyFiles: ['.env.local'],
+    postCreate: 'npm install',
+  },
+};
+```
+
+Plugins are only available when their configuration key is present.
+
+## Built-in Plugins
 
 ### Select Plugin
 
@@ -22,41 +44,59 @@ Switch config options in source files using `@pik` markers.
 const env = 'LOCAL';      // @pik:option LOCAL
 ```
 
-#### 2. Create a config file
+#### 2. Run commands
 
-Create `pik.config.ts` in your project root:
-
-```typescript
-import { defineConfig } from '@lsst/pik';
-
-export default defineConfig({
-  select: {
-    include: ['src/**/*.ts', '.env'],
-  },
-});
+```bash
+pik select              # Interactive mode
+pik select list         # List all selectors
+pik select set Environment DEV  # Set directly
 ```
 
-#### 3. Run commands
+### Worktree Plugin
+
+Manage git worktrees with automatic setup.
 
 ```bash
-# Interactive mode
-pik select
+pik worktree              # Interactive mode
+pik worktree create       # Create a new worktree
+pik worktree list         # List all worktrees
+pik worktree remove       # Remove a worktree
+```
 
-# List all selectors
-pik select list
+## External Plugins
 
-# Set a specific option
-pik select set Environment DEV
+Add third-party or custom plugins:
+
+```typescript
+import { myPlugin } from 'pik-plugin-my';
+
+export default {
+  plugins: [
+    myPlugin({ apiKey: 'xxx' }),
+  ],
+  select: { include: ['src/**/*.ts'] },
+};
 ```
 
 ## Commands
 
+### Select
+
 | Command | Alias | Description |
 |---------|-------|-------------|
 | `pik select` | `sel` | Interactive selection mode |
 | `pik select list` | `ls` | Show all selectors and their state |
 | `pik select set <selector> <option>` | - | Set an option directly |
 
+### Worktree
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `pik worktree` | `wt` | Interactive worktree menu |
+| `pik worktree create [name]` | `add` | Create a new worktree |
+| `pik worktree list` | `ls` | List all worktrees |
+| `pik worktree remove [path]` | `rm` | Remove a worktree |
+
 ## Marker Syntax
 
 - `@pik:select <name>` - Defines a selector group
@@ -68,7 +108,8 @@ Commented lines are inactive, uncommented lines are active.
 
 | Extensions | Comment Style |
 |------------|---------------|
-| `.ts`, `.js`, `.tsx`, `.jsx` | `//` |
+| `.ts`, `.js`, `.tsx`, `.jsx`, `.mts`, `.mjs` | `//` |
+| `.html`, `.htm` | `//` and `<!-- -->` |
 | `.sh`, `.bash`, `.zsh`, `.py`, `.yaml`, `.yml`, `.env` | `#` |
 
 ## License

package/dist/lib/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/lib/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAuB5D,eAAO,MAAM,OAAO,SAGG,CAAC;AAExB;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAgE9D"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/lib/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA6C3E,eAAO,MAAM,OAAO,SAGG,CAAC;AAExB;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAgE9D"}

package/dist/lib/program.js

@@ -1,23 +1,43 @@
 import { Command } from 'commander';
 import { select, Separator } from '@inquirer/prompts';
 import pc from 'picocolors';
-import { loadConfig } from '@lsst/pik-core';
+import { loadConfig, isValidPlugin } from '@lsst/pik-core';
 import { selectPlugin } from '@lsst/pik-plugin-select';
 import { worktreePlugin } from '@lsst/pik-plugin-worktree';
 import pkg from '../../package.json' with { type: 'json' };
-// List of all available plugins
-const allPlugins = [selectPlugin, worktreePlugin];
+// Built-in plugins
+const builtinPlugins = [selectPlugin, worktreePlugin];
 /**
  * Get plugins that are enabled in the config.
- * A plugin is enabled if its command key exists in the config (even as empty object).
+ * - Built-in plugins are enabled if their command key exists in config
+ * - External plugins from the `plugins` array are added directly
  */
 async function getEnabledPlugins() {
     const config = await loadConfig();
     if (!config) {
-        // No config - no plugins enabled for interactive mode
+        // No config - no plugins enabled
         return [];
     }
-    return allPlugins.filter((plugin) => plugin.command in config);
+    const enabledPlugins = [];
+    // Add built-in plugins that have config keys
+    for (const plugin of builtinPlugins) {
+        if (plugin.command in config) {
+            enabledPlugins.push(plugin);
+        }
+    }
+    // Add external plugins from config
+    if (config.plugins && Array.isArray(config.plugins)) {
+        for (const plugin of config.plugins) {
+            if (isValidPlugin(plugin)) {
+                enabledPlugins.push(plugin);
+            }
+            else {
+                console.error(pc.red('Invalid plugin in config.plugins array'));
+                console.error(pc.dim('Each plugin must have: name, description, command, register'));
+            }
+        }
+    }
+    return enabledPlugins;
 }
 export const program = new Command()
     .name(pkg.name)

package/dist/lib/program.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=program.spec.d.ts.map

package/dist/lib/program.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.spec.d.ts","sourceRoot":"","sources":["../../src/lib/program.spec.ts"],"names":[],"mappings":""}

package/dist/lib/program.spec.js

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+// Mock the config and plugins before importing program
+vi.mock('@lsst/pik-core', async () => {
+    const actual = await vi.importActual('@lsst/pik-core');
+    return {
+        ...actual,
+        loadConfig: vi.fn(),
+    };
+});
+vi.mock('@lsst/pik-plugin-select', () => ({
+    selectPlugin: {
+        name: 'Select',
+        description: 'Mock select plugin',
+        command: 'select',
+        register: vi.fn(),
+    },
+}));
+vi.mock('@lsst/pik-plugin-worktree', () => ({
+    worktreePlugin: {
+        name: 'Worktree',
+        description: 'Mock worktree plugin',
+        command: 'worktree',
+        register: vi.fn(),
+    },
+}));
+describe('program', () => {
+    let loadConfigMock;
+    beforeEach(async () => {
+        vi.resetModules();
+        const pikCore = await import('@lsst/pik-core');
+        loadConfigMock = pikCore.loadConfig;
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('initializeProgram', () => {
+        it('should return empty array when no config exists', async () => {
+            loadConfigMock.mockResolvedValue(null);
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toEqual([]);
+        });
+        it('should load built-in plugins when their config keys exist', async () => {
+            loadConfigMock.mockResolvedValue({
+                select: { include: ['*.ts'] },
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(1);
+            expect(plugins[0].command).toBe('select');
+        });
+        it('should load multiple built-in plugins when configured', async () => {
+            loadConfigMock.mockResolvedValue({
+                select: { include: ['*.ts'] },
+                worktree: { baseDir: '../' },
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(2);
+            expect(plugins.map((p) => p.command)).toContain('select');
+            expect(plugins.map((p) => p.command)).toContain('worktree');
+        });
+        it('should load external plugins from plugins array', async () => {
+            const externalPlugin = {
+                name: 'External Plugin',
+                description: 'Test external plugin',
+                command: 'external',
+                register: vi.fn(),
+            };
+            loadConfigMock.mockResolvedValue({
+                plugins: [externalPlugin],
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(1);
+            expect(plugins[0].name).toBe('External Plugin');
+            expect(plugins[0].command).toBe('external');
+        });
+        it('should combine built-in and external plugins', async () => {
+            const externalPlugin = {
+                name: 'External Plugin',
+                description: 'Test external plugin',
+                command: 'external',
+                register: vi.fn(),
+            };
+            loadConfigMock.mockResolvedValue({
+                plugins: [externalPlugin],
+                select: { include: ['*.ts'] },
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(2);
+            expect(plugins.map((p) => p.command)).toContain('select');
+            expect(plugins.map((p) => p.command)).toContain('external');
+        });
+        it('should register external plugins with the program', async () => {
+            const registerFn = vi.fn();
+            const externalPlugin = {
+                name: 'External Plugin',
+                description: 'Test external plugin',
+                command: 'external',
+                register: registerFn,
+            };
+            loadConfigMock.mockResolvedValue({
+                plugins: [externalPlugin],
+            });
+            const { initializeProgram } = await import('./program.js');
+            await initializeProgram();
+            expect(registerFn).toHaveBeenCalledTimes(1);
+            expect(registerFn).toHaveBeenCalledWith(expect.any(Command));
+        });
+        it('should skip invalid plugins and log error', async () => {
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const invalidPlugin = {
+                name: 'Invalid',
+                // missing description, command, register
+            };
+            loadConfigMock.mockResolvedValue({
+                plugins: [invalidPlugin],
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(0);
+            expect(consoleSpy).toHaveBeenCalled();
+            consoleSpy.mockRestore();
+        });
+        it('should load multiple external plugins', async () => {
+            const plugin1 = {
+                name: 'Plugin 1',
+                description: 'First plugin',
+                command: 'first',
+                register: vi.fn(),
+            };
+            const plugin2 = {
+                name: 'Plugin 2',
+                description: 'Second plugin',
+                command: 'second',
+                register: vi.fn(),
+            };
+            loadConfigMock.mockResolvedValue({
+                plugins: [plugin1, plugin2],
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(2);
+            expect(plugins[0].command).toBe('first');
+            expect(plugins[1].command).toBe('second');
+        });
+        it('should handle plugin factory pattern (function returning plugin)', async () => {
+            // This simulates: myPlugin({ config: 'value' }) in the config
+            const pluginFactory = (config) => ({
+                name: 'Factory Plugin',
+                description: `Plugin with key: ${config.apiKey}`,
+                command: 'factory',
+                register: vi.fn(),
+            });
+            const factoryPlugin = pluginFactory({ apiKey: 'test-key' });
+            loadConfigMock.mockResolvedValue({
+                plugins: [factoryPlugin],
+            });
+            const { initializeProgram } = await import('./program.js');
+            const plugins = await initializeProgram();
+            expect(plugins).toHaveLength(1);
+            expect(plugins[0].name).toBe('Factory Plugin');
+            expect(plugins[0].description).toBe('Plugin with key: test-key');
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsst/pik",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "CLI tool for switching config options in source files",
   "type": "module",
   "license": "MIT",