@ulthon/ul-opencode-event 0.1.0 → 0.1.3

package/README.md

@@ -135,6 +135,58 @@ You can configure multiple channels, and all enabled channels will receive notif
 }
 ```
 
+## CLI Tool
+
+This package includes a CLI tool to test your notification channel configuration before running OpenCode.
+
+### Test Command
+
+```bash
+# Test all channels (validates config, tests connection, sends test email)
+npx @ulthon/ul-opencode-event test
+
+# Test a specific channel by name
+npx @ulthon/ul-opencode-event test --channel "My Email"
+
+# Only verify connection without sending email
+npx @ulthon/ul-opencode-event test --no-send
+```
+
+### What the test command does:
+
+1. **Configuration validation**: Checks if the config file exists and has valid format
+2. **SMTP connection test**: Verifies that the SMTP server is reachable and credentials work
+3. **Test email**: Sends a test email to configured recipients (unless `--no-send` is used)
+
+### Test output example:
+
+```
+[ul-opencode-event-cli] Starting channel test...
+[ul-opencode-event-cli] Loaded project config: ./ul-opencode-event.json
+[ul-opencode-event-cli] Found 1 channel(s) to test
+
+[ul-opencode-event-cli] Testing channel: "My Email"
+  Type: smtp
+  Recipients: user@example.com
+
+  [1/3] Validating configuration...
+  [OK] Configuration is valid
+
+  [2/3] Testing SMTP connection to smtp.example.com:465...
+  [OK] Connection successful
+
+  [3/3] Sending test email...
+  [OK] Test email sent successfully
+  Message ID: <xxx>
+
+  [SUCCESS] Channel "My Email" passed all tests
+  Please check the inbox of: user@example.com
+
+[ul-opencode-event-cli] Test Summary:
+  Passed: 1
+  Failed: 0
+```
+
 ## Troubleshooting
 
 ### No notifications sent
@@ -142,6 +194,14 @@ You can configure multiple channels, and all enabled channels will receive notif
 1. Check if `enabled: true` is set
 2. Check if the event type is enabled in `events`
 3. Check SMTP credentials are correct
+4. Ensure plugin config file exists at `.opencode/ul-opencode-event.json`, `./ul-opencode-event.json`, or `~/.config/opencode/ul-opencode-event.json`
+5. Enable debug logs with environment variable `UL_OPENCODE_EVENT_DEBUG=1`
+
+### How to view logs
+
+- Start OpenCode from terminal to view stdout/stderr logs
+- Plugin logs use prefix `[ul-opencode-event]`
+- You will see errors for JSON parse failure, invalid config shape, and event handling failures
 
 ### SMTP authentication failed
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for testing notification channel configuration
+ *
+ * Usage:
+ *   npx @ulthon/ul-opencode-event test
+ *   npx @ulthon/ul-opencode-event test --channel "My Channel"
+ *   npx @ulthon/ul-opencode-event test --no-send  # Only verify connection, don't send email
+ */
+import * as nodemailer from 'nodemailer';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const CLI_PREFIX = '[ul-opencode-event-cli]';
+/**
+ * Print usage information
+ */
+function printUsage() {
+    console.log(`
+Usage: npx @ulthon/ul-opencode-event test [options]
+
+Options:
+  --channel <name>   Test only the channel with this name
+  --no-send          Only verify connection, don't send test email
+  --help             Show this help message
+
+Examples:
+  npx @ulthon/ul-opencode-event test
+  npx @ulthon/ul-opencode-event test --channel "Primary Email"
+  npx @ulthon/ul-opencode-event test --no-send
+`);
+}
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        noSend: false,
+    };
+    let command = null;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            printUsage();
+            process.exit(0);
+        }
+        else if (arg === '--channel') {
+            options.channelName = args[++i];
+        }
+        else if (arg === '--no-send') {
+            options.noSend = true;
+        }
+        else if (!arg.startsWith('-')) {
+            command = arg;
+        }
+    }
+    return { command, options };
+}
+/**
+ * Validate channel configuration
+ */
+function validateChannel(channel) {
+    const errors = [];
+    // Check type
+    if (channel.type !== 'smtp') {
+        errors.push(`Unsupported channel type: "${channel.type}". Only "smtp" is supported.`);
+        return { valid: false, errors };
+    }
+    // Check enabled
+    if (channel.enabled === false) {
+        errors.push('Channel is disabled (enabled: false)');
+        return { valid: false, errors };
+    }
+    // Check recipients
+    if (!channel.recipients || channel.recipients.length === 0) {
+        errors.push('No recipients configured');
+        return { valid: false, errors };
+    }
+    // Check SMTP config
+    const config = channel.config;
+    if (!config.host) {
+        errors.push('SMTP host is missing');
+    }
+    if (!config.port) {
+        errors.push('SMTP port is missing');
+    }
+    if (!config.auth?.user) {
+        errors.push('SMTP auth.user is missing');
+    }
+    if (!config.auth?.pass) {
+        errors.push('SMTP auth.pass is missing');
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Create SMTP transporter
+ */
+function createTransporter(channel) {
+    const config = channel.config;
+    return nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure ?? (config.port === 465),
+        auth: {
+            user: config.auth.user,
+            pass: config.auth.pass,
+        },
+    });
+}
+/**
+ * Test SMTP connection
+ */
+async function testConnection(channel) {
+    try {
+        const transporter = createTransporter(channel);
+        await transporter.verify();
+        return { success: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+    }
+}
+/**
+ * Send test email
+ */
+async function sendTestEmail(channel) {
+    try {
+        const config = channel.config;
+        const transporter = createTransporter(channel);
+        const fromName = channel.name || 'OpenCode Notification Test';
+        const timestamp = new Date().toISOString();
+        const result = await transporter.sendMail({
+            from: `"${fromName}" <${config.auth.user}>`,
+            to: channel.recipients.join(', '),
+            subject: `[Test] OpenCode Notification Channel Test - ${timestamp}`,
+            text: `This is a test email from OpenCode notification plugin.
+
+Channel: ${channel.name || 'unnamed'}
+Type: ${channel.type}
+Time: ${timestamp}
+
+If you received this email, your notification channel is configured correctly.`,
+            html: `
+        <h2>OpenCode Notification Channel Test</h2>
+        <p>This is a test email from OpenCode notification plugin.</p>
+        <hr>
+        <ul>
+          <li><strong>Channel:</strong> ${channel.name || 'unnamed'}</li>
+          <li><strong>Type:</strong> ${channel.type}</li>
+          <li><strong>Time:</strong> ${timestamp}</li>
+        </ul>
+        <hr>
+        <p style="color: green;">If you received this email, your notification channel is configured correctly.</p>
+      `,
+        });
+        return { success: true, messageId: result.messageId };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+    }
+}
+/**
+ * Test a single channel
+ */
+async function testChannel(channel, options) {
+    const channelName = channel.name || 'unnamed';
+    console.log(`\n${CLI_PREFIX} Testing channel: "${channelName}"`);
+    console.log(`  Type: ${channel.type}`);
+    console.log(`  Recipients: ${channel.recipients?.join(', ') || 'none'}`);
+    // Step 1: Validate configuration
+    console.log(`\n  [1/3] Validating configuration...`);
+    const validation = validateChannel(channel);
+    if (!validation.valid) {
+        console.log(`  [FAIL] Configuration validation failed:`);
+        validation.errors.forEach(err => console.log(`    - ${err}`));
+        return false;
+    }
+    console.log(`  [OK] Configuration is valid`);
+    // Step 2: Test connection
+    const smtpConfig = channel.config;
+    console.log(`\n  [2/3] Testing SMTP connection to ${smtpConfig.host}:${smtpConfig.port}...`);
+    const connectionResult = await testConnection(channel);
+    if (!connectionResult.success) {
+        console.log(`  [FAIL] Connection failed: ${connectionResult.error}`);
+        return false;
+    }
+    console.log(`  [OK] Connection successful`);
+    // Step 3: Send test email (if not skipped)
+    if (options.noSend) {
+        console.log(`\n  [3/3] Skipping test email (--no-send flag)`);
+        console.log(`\n  [SUCCESS] Channel "${channelName}" passed all tests (connection only)`);
+        return true;
+    }
+    console.log(`\n  [3/3] Sending test email...`);
+    const sendResult = await sendTestEmail(channel);
+    if (!sendResult.success) {
+        console.log(`  [FAIL] Failed to send test email: ${sendResult.error}`);
+        return false;
+    }
+    console.log(`  [OK] Test email sent successfully`);
+    console.log(`  Message ID: ${sendResult.messageId}`);
+    console.log(`\n  [SUCCESS] Channel "${channelName}" passed all tests`);
+    console.log(`  Please check the inbox of: ${channel.recipients?.join(', ')}`);
+    return true;
+}
+/**
+ * Load configuration (simplified version that loads from file)
+ * This is similar to config.ts but returns all channels including disabled ones
+ */
+function loadConfigForTesting() {
+    // Config file paths
+    const globalPath = path.join(os.homedir(), '.config', 'opencode', 'ul-opencode-event.json');
+    const projectOpencodePath = path.join(process.cwd(), '.opencode', 'ul-opencode-event.json');
+    const projectLocalPath = path.join(process.cwd(), 'ul-opencode-event.json');
+    let globalConfig = null;
+    let projectConfig = null;
+    // Load global config
+    if (fs.existsSync(globalPath)) {
+        try {
+            const content = fs.readFileSync(globalPath, 'utf-8');
+            globalConfig = JSON.parse(content);
+            console.log(`${CLI_PREFIX} Loaded global config: ${globalPath}`);
+        }
+        catch (error) {
+            console.error(`${CLI_PREFIX} Failed to parse global config: ${globalPath}`, error);
+        }
+    }
+    // Load project config
+    const projectPath = fs.existsSync(projectOpencodePath) ? projectOpencodePath :
+        fs.existsSync(projectLocalPath) ? projectLocalPath : null;
+    if (projectPath) {
+        try {
+            const content = fs.readFileSync(projectPath, 'utf-8');
+            projectConfig = JSON.parse(content);
+            console.log(`${CLI_PREFIX} Loaded project config: ${projectPath}`);
+        }
+        catch (error) {
+            console.error(`${CLI_PREFIX} Failed to parse project config: ${projectPath}`, error);
+        }
+    }
+    // If no configs found
+    if (!globalConfig && !projectConfig) {
+        console.error(`${CLI_PREFIX} No configuration file found.`);
+        console.error(`${CLI_PREFIX} Checked locations:`);
+        console.error(`  - ${globalPath}`);
+        console.error(`  - ${projectOpencodePath}`);
+        console.error(`  - ${projectLocalPath}`);
+        process.exit(1);
+    }
+    // Merge channels (project overrides global by name)
+    const globalChannels = globalConfig?.channels || [];
+    const projectChannels = projectConfig?.channels || [];
+    const mergedChannels = [...globalChannels];
+    for (const projectChannel of projectChannels) {
+        if (projectChannel.name) {
+            const existingIndex = mergedChannels.findIndex(c => c.name === projectChannel.name);
+            if (existingIndex >= 0) {
+                mergedChannels[existingIndex] = projectChannel;
+                continue;
+            }
+        }
+        mergedChannels.push(projectChannel);
+    }
+    return { channels: mergedChannels };
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const { command, options } = parseArgs();
+    if (command !== 'test') {
+        console.error(`${CLI_PREFIX} Unknown command: "${command || '(none)'}"`);
+        printUsage();
+        process.exit(1);
+    }
+    console.log(`${CLI_PREFIX} Starting channel test...`);
+    // Load configuration
+    const config = loadConfigForTesting();
+    if (config.channels.length === 0) {
+        console.error(`${CLI_PREFIX} No channels configured.`);
+        process.exit(1);
+    }
+    // Filter channels by name if specified
+    let channelsToTest = config.channels;
+    if (options.channelName) {
+        channelsToTest = config.channels.filter(c => c.name === options.channelName);
+        if (channelsToTest.length === 0) {
+            console.error(`${CLI_PREFIX} No channel found with name: "${options.channelName}"`);
+            console.error(`${CLI_PREFIX} Available channels:`);
+            config.channels.forEach(c => console.error(`  - ${c.name || 'unnamed'}`));
+            process.exit(1);
+        }
+    }
+    console.log(`${CLI_PREFIX} Found ${channelsToTest.length} channel(s) to test`);
+    // Test each channel
+    let successCount = 0;
+    let failCount = 0;
+    for (const channel of channelsToTest) {
+        const success = await testChannel(channel, options);
+        if (success) {
+            successCount++;
+        }
+        else {
+            failCount++;
+        }
+    }
+    // Summary
+    console.log(`\n${CLI_PREFIX} Test Summary:`);
+    console.log(`  Passed: ${successCount}`);
+    console.log(`  Failed: ${failCount}`);
+    if (failCount > 0) {
+        process.exit(1);
+    }
+}
+// Run CLI
+main().catch(error => {
+    console.error(`${CLI_PREFIX} Unexpected error:`, error);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { NotificationConfig } from './types';
+import type { NotificationConfig } from './types.js';
 /**
  * Load and merge notification configuration
  *

package/dist/config.js

@@ -0,0 +1,151 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const SUPPORTED_CHANNEL_TYPES = ['smtp'];
+const LOG_PREFIX = '[ul-opencode-event]';
+const DEBUG_ENABLED = process.env.UL_OPENCODE_EVENT_DEBUG === '1' || process.env.UL_OPENCODE_EVENT_DEBUG === 'true';
+/**
+ * Default configuration returned when no config files exist
+ */
+const DEFAULT_CONFIG = {
+    channels: [],
+};
+/**
+ * Load and parse a JSON config file if it exists
+ */
+function loadConfigFile(filePath) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const config = JSON.parse(content);
+        if (!Array.isArray(config.channels)) {
+            console.error(`${LOG_PREFIX} Invalid config format in ${filePath}: "channels" must be an array`);
+            return null;
+        }
+        if (DEBUG_ENABLED) {
+            console.info(`${LOG_PREFIX} Loaded config: ${filePath} (${config.channels.length} channels)`);
+        }
+        return config;
+    }
+    catch (error) {
+        console.error(`${LOG_PREFIX} Failed to parse config file: ${filePath}`, error);
+        return null;
+    }
+}
+/**
+ * Validate that all channel types are supported
+ * @throws Error if any channel has an unsupported type
+ */
+function validateChannelTypes(channels) {
+    for (const channel of channels) {
+        if (!SUPPORTED_CHANNEL_TYPES.includes(channel.type)) {
+            throw new Error(`Unsupported channel type: "${channel.type}". Supported types: ${SUPPORTED_CHANNEL_TYPES.join(', ')}`);
+        }
+    }
+}
+/**
+ * Deep merge channels by name
+ * - If project channel name matches global channel name, project overrides global
+ * - If no name match, project channels are appended to global channels
+ */
+function mergeChannels(globalChannels, projectChannels) {
+    if (!globalChannels?.length && !projectChannels?.length) {
+        return [];
+    }
+    if (!globalChannels?.length) {
+        return projectChannels ?? [];
+    }
+    if (!projectChannels?.length) {
+        return globalChannels;
+    }
+    const result = [...globalChannels];
+    for (const projectChannel of projectChannels) {
+        const existingIndex = result.findIndex((c) => c.name !== undefined && c.name === projectChannel.name);
+        if (existingIndex >= 0) {
+            // Override global channel with project channel (same name)
+            result[existingIndex] = projectChannel;
+        }
+        else {
+            // Append project channel (no name match)
+            result.push(projectChannel);
+        }
+    }
+    return result;
+}
+/**
+ * Filter channels to only include enabled ones
+ * A channel is enabled if enabled is true or undefined (defaults to true)
+ */
+function filterEnabledChannels(channels) {
+    return channels.filter((channel) => channel.enabled !== false);
+}
+/**
+ * Get global config file path: ~/.config/opencode/ul-opencode-event.json
+ */
+function getGlobalConfigPath() {
+    return path.join(os.homedir(), '.config', 'opencode', 'ul-opencode-event.json');
+}
+/**
+ * Get project config file path
+ * Priority: .opencode/ul-opencode-event.json > ./ul-opencode-event.json
+ */
+function getProjectConfigPath() {
+    const opencodePath = path.join(process.cwd(), '.opencode', 'ul-opencode-event.json');
+    if (fs.existsSync(opencodePath)) {
+        return opencodePath;
+    }
+    const localPath = path.join(process.cwd(), 'ul-opencode-event.json');
+    if (fs.existsSync(localPath)) {
+        return localPath;
+    }
+    return null;
+}
+/**
+ * Load and merge notification configuration
+ *
+ * Config locations (in order of priority):
+ * 1. Project-level: .opencode/ul-opencode-event.json or ./ul-opencode-event.json
+ * 2. Global: ~/.config/opencode/ul-opencode-event.json
+ *
+ * Merge strategy:
+ * - Channels are merged by `name` field
+ * - If names match, project channel overrides global channel
+ * - If no name match, project channels are appended to global channels
+ *
+ * Filtering:
+ * - Only returns channels where enabled is true (or undefined, which defaults to true)
+ * - Channels with enabled: false are excluded
+ *
+ * Validation:
+ * - Channel type must be 'smtp' (only supported type in phase 1)
+ * - Throws clear error for unsupported channel types
+ *
+ * @returns Merged and filtered configuration, or default config if no files exist
+ * @throws Error if any channel has an unsupported type
+ */
+export function loadConfig() {
+    // Load global config
+    const globalConfigPath = getGlobalConfigPath();
+    const globalConfig = loadConfigFile(globalConfigPath);
+    // Load project config
+    const projectConfigPath = getProjectConfigPath();
+    const projectConfig = projectConfigPath ? loadConfigFile(projectConfigPath) : null;
+    // If no configs exist, return default
+    if (!globalConfig && !projectConfig) {
+        if (DEBUG_ENABLED) {
+            console.info(`${LOG_PREFIX} No config found. Checked: ${globalConfigPath}, ${path.join(process.cwd(), '.opencode', 'ul-opencode-event.json')}, ${path.join(process.cwd(), 'ul-opencode-event.json')}`);
+        }
+        return DEFAULT_CONFIG;
+    }
+    // Merge channels
+    const mergedChannels = mergeChannels(globalConfig?.channels, projectConfig?.channels);
+    // Validate channel types
+    validateChannelTypes(mergedChannels);
+    // Filter enabled channels
+    const enabledChannels = filterEnabledChannels(mergedChannels);
+    return {
+        channels: enabledChannels,
+    };
+}

package/dist/email.d.ts

@@ -1,4 +1,4 @@
-import type { Channel } from './types';
+import type { Channel } from './types.js';
 export interface EmailSender {
     send: (subject: string, body: string) => Promise<void>;
 }

package/dist/email.js

@@ -0,0 +1,56 @@
+/**
+ * Email sender module for SMTP-based notifications
+ */
+import * as nodemailer from 'nodemailer';
+/**
+ * Creates an email sender for the given SMTP channel
+ * @param channel - The channel configuration (must be SMTP type)
+ * @returns EmailSender instance or null if channel is invalid/disabled
+ */
+export function createEmailSender(channel) {
+    // Type guard: return null for non-smtp channels
+    if (channel.type !== 'smtp') {
+        return null;
+    }
+    // Return null for disabled channels
+    if (channel.enabled === false) {
+        return null;
+    }
+    // Return null if no recipients configured
+    if (!channel.recipients || channel.recipients.length === 0) {
+        return null;
+    }
+    const config = channel.config;
+    const fromName = channel.name || 'Notification';
+    // Create nodemailer transport with SMTP config
+    const transport = nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: {
+            user: config.auth.user,
+            pass: config.auth.pass,
+        },
+    });
+    // Set security options
+    transport.set('disableFileAccess', true);
+    transport.set('disableUrlAccess', true);
+    return {
+        async send(subject, body) {
+            try {
+                await transport.sendMail({
+                    from: `"${fromName}" <${config.auth.user}>`,
+                    to: channel.recipients.join(', '),
+                    subject,
+                    html: body,
+                    text: body,
+                });
+            }
+            catch (error) {
+                // Silent failure: log error but don't throw
+                const timestamp = new Date().toISOString();
+                console.error(`[${timestamp}] [${fromName}] Failed to send email:`, error);
+            }
+        },
+    };
+}

package/dist/handler.d.ts

@@ -1,7 +1,7 @@
 /**
  * Multi-channel event handler for notifications
  */
-import type { NotificationConfig, EventPayload, EventType } from './types';
+import type { NotificationConfig, EventPayload, EventType } from './types.js';
 export interface EventHandler {
     handle: (eventType: EventType, payload: EventPayload) => Promise<void>;
 }