@lsst/pik 0.5.1 → 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/bin/pik.js

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
-import { program } from '../lib/program.js';
+import { program, initializeProgram } from '../lib/program.js';
+await initializeProgram();
 program.parse();

package/dist/lib/program.d.ts

@@ -1,3 +1,8 @@
 import { Command } from 'commander';
+import { type PikPlugin } from '@lsst/pik-core';
 export declare const program: Command;
+/**
+ * Initialize the program by loading config and registering enabled plugins.
+ */
+export declare function initializeProgram(): Promise<PikPlugin[]>;
 //# sourceMappingURL=program.d.ts.map

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;AAWpC,eAAO,MAAM,OAAO,SAGG,CAAC"}
+{"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,49 +1,107 @@
 import { Command } from 'commander';
 import { select, Separator } from '@inquirer/prompts';
 import pc from 'picocolors';
+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 available plugins
-const plugins = [selectPlugin, worktreePlugin];
+// Built-in plugins
+const builtinPlugins = [selectPlugin, worktreePlugin];
+/**
+ * Get plugins that are enabled in the config.
+ * - 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
+        return [];
+    }
+    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)
     .description(pkg.description)
     .version(pkg.version);
-// Register all plugins
-for (const plugin of plugins) {
-    plugin.register(program);
-}
-// Default action: show main menu if multiple plugins, otherwise run default plugin
-program.action(async () => {
-    if (plugins.length === 1) {
-        // Single plugin - run its default command
-        const plugin = plugins[0];
-        const cmd = program.commands.find((c) => c.name() === plugin.command);
-        if (cmd) {
-            await cmd.parseAsync([], { from: 'user' });
-        }
+/**
+ * Initialize the program by loading config and registering enabled plugins.
+ */
+export async function initializeProgram() {
+    const plugins = await getEnabledPlugins();
+    // Register only enabled plugins
+    for (const plugin of plugins) {
+        plugin.register(program);
     }
-    else {
-        // Multiple plugins - show selection menu
-        const EXIT_VALUE = Symbol('exit');
-        const selectedPlugin = await select({
-            message: 'Select a tool',
-            choices: [
-                ...plugins.map((plugin) => ({
-                    name: `${pc.bold(plugin.name)} - ${plugin.description}`,
-                    value: plugin,
-                })),
-                new Separator(),
-                { name: pc.dim('Exit'), value: EXIT_VALUE },
-            ],
-        });
-        if (selectedPlugin === EXIT_VALUE) {
+    // Default action: show main menu with enabled plugins
+    program.action(async () => {
+        if (plugins.length === 0) {
+            console.log(pc.yellow('No plugins configured.'));
+            console.log(pc.dim('Add plugin config to pik.config.ts to enable plugins.'));
+            console.log(pc.dim('Example: { select: {}, worktree: {} }'));
             return;
         }
-        const cmd = program.commands.find((c) => c.name() === selectedPlugin.command);
-        if (cmd) {
-            await cmd.parseAsync([], { from: 'user' });
+        if (plugins.length === 1) {
+            // Single plugin - run its default command
+            const plugin = plugins[0];
+            const cmd = program.commands.find((c) => c.name() === plugin.command);
+            if (cmd) {
+                await cmd.parseAsync([], { from: 'user' });
+            }
         }
-    }
-});
+        else {
+            // Multiple plugins - show selection menu in a loop
+            const EXIT_VALUE = Symbol('exit');
+            while (true) {
+                let selectedPlugin;
+                try {
+                    selectedPlugin = await select({
+                        message: 'Select a tool',
+                        choices: [
+                            ...plugins.map((plugin) => ({
+                                name: `${pc.bold(plugin.name)} - ${plugin.description}`,
+                                value: plugin,
+                            })),
+                            new Separator(),
+                            { name: pc.dim('Exit'), value: EXIT_VALUE },
+                        ],
+                    });
+                }
+                catch (error) {
+                    // Handle Ctrl+C
+                    if (error instanceof Error && error.name === 'ExitPromptError') {
+                        return;
+                    }
+                    throw error;
+                }
+                if (selectedPlugin === EXIT_VALUE) {
+                    return;
+                }
+                const cmd = program.commands.find((c) => c.name() === selectedPlugin.command);
+                if (cmd) {
+                    await cmd.parseAsync([], { from: 'user' });
+                }
+            }
+        }
+    });
+    return plugins;
+}

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.1",
+  "version": "0.5.3",
   "description": "CLI tool for switching config options in source files",
   "type": "module",
   "license": "MIT",