@ulthon/ul-opencode-event 0.1.1 → 0.1.4

package/README.md

@@ -2,33 +2,42 @@
 
 OpenCode notification plugin that sends email notifications when session events occur.
 
-## Installation
+## Quick Start
 
 ```bash
+# 1. 安装
 npm install @ulthon/ul-opencode-event
-```
 
-Then add to your OpenCode configuration:
+# 2. 创建配置文件（项目根目录）
+cp node_modules/@ulthon/ul-opencode-event/examples/ul-opencode-event.json ./
+
+# 3. 编辑配置，填入你的 SMTP 信息
 
+# 4. 测试连接
+npx @ulthon/ul-opencode-event test
+
+# 5. 添加到 OpenCode 配置
+# 在 .opencode/settings.json 中添加:
+# { "plugin": ["@ulthon/ul-opencode-event"] }
+```
+## Installation
+```bash
+npm install @ulthon/ul-opencode-event
+```
+Then add to your OpenCode configuration (`.opencode/settings.json`):
 ```json
 {
   "plugin": ["@ulthon/ul-opencode-event"]
 }
 ```
-
 ## Configuration
-
 ### Configuration File Locations
-
 The plugin looks for configuration in these 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`
-
 Project-level configuration overrides global configuration (channels are merged by name).
-
-### Configuration Format
-
+### Minimal Configuration
+Create `ul-opencode-event.json` in your project root:
 ```json
 {
   "channels": [
@@ -47,49 +56,143 @@ Project-level configuration overrides global configuration (channels are merged
       },
       "recipients": ["receiver@example.com"],
       "events": {
-        "created": true,
+        "idle": true,
+        "error": true
+      }
+    }
+  ]
+}
+```
+### Common SMTP Servers
+| Provider | Host | Port | Secure | Auth |
+|----------|------|------|--------|------|
+| QQ Mail | smtp.qq.com | 465 | true | Authorization code |
+| 163 Mail | smtp.163.com | 465 | true | Authorization code |
+| Gmail | smtp.gmail.com | 587 | false | App Password |
+| Outlook | smtp.office365.com | 587 | false | Password |
+> **Note**: For QQ/163 Mail, use the authorization code (授权码), not your login password.
+> For Gmail, use an App Password with 2FA enabled.
+### Full Configuration Example
+```json
+{
+  "channels": [
+    {
+      "type": "smtp",
+      "enabled": true,
+      "name": "QQ邮箱",
+      "config": {
+        "host": "smtp.qq.com",
+        "port": 465,
+        "secure": true,
+        "auth": {
+          "user": "your@qq.com",
+          "pass": "your-authorization-code"
+        }
+      },
+      "recipients": ["admin@example.com", "dev-team@example.com"],
+      "events": {
+        "created": false,
         "idle": true,
         "error": true
       },
       "templates": {
-        "created": {
-          "subject": "[OpenCode] Task Started - {{projectName}}",
-          "body": "Task started at {{timestamp}}"
+        "idle": {
+          "subject": "[OpenCode] 任务完成 - {{projectName}}",
+          "body": "任务已完成\n\n项目: {{projectName}}\n时间: {{timestamp}}\n耗时: {{duration}}\n消息: {{message}}"
+        },
+        "error": {
+          "subject": "[OpenCode] 任务错误 - {{projectName}}",
+          "body": "任务发生错误\n\n项目: {{projectName}}\n时间: {{timestamp}}\n错误: {{error}}"
         }
       }
     }
   ]
 }
 ```
-
-See `examples/ul-opencode-event.json` for a complete example.
-
 ### Channel Configuration
-
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `type` | string | Yes | Channel type: `smtp` (more coming soon) |
+| `type` | string | Yes | Channel type: `smtp` |
 | `enabled` | boolean | No | Whether this channel is active (default: true) |
 | `name` | string | No | Channel name for identification |
-| `config` | object | Yes | Channel-specific configuration |
-| `recipients` | string[] | Yes* | Email recipients (*required for smtp*) |
+| `config` | object | Yes | SMTP configuration |
+| `recipients` | string[] | Yes | Email recipients |
 | `events` | object | No | Which events to notify |
 | `templates` | object | No | Custom templates for each event |
-
 ### SMTP Configuration
-
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `host` | string | Yes | SMTP server hostname |
+| `host` | string | Yes | SMTP server hostname or IPv4/IPv6 address |
 | `port` | number | Yes | SMTP port (465 for SSL, 587 for STARTTLS) |
 | `secure` | boolean | No | Use SSL (default: true for port 465) |
-| `auth.user` | string | Yes | SMTP username |
-| `auth.pass` | string | Yes | SMTP password or app password |
+| `localAddress` | string | No | Local interface to bind for IPv4/IPv6 control |
+| `auth.user` | string | Yes | SMTP username (usually your email) |
+| `auth.pass` | string | Yes | SMTP password or authorization code |
 
-## Template Variables
+### IPv4/IPv6 Configuration
 
-Use these variables in your subject and body templates:
+By default, the plugin automatically supports both IPv4 and IPv6. Nodemailer will:
+- Resolve DNS to both IPv4 (A) and IPv6 (AAAA) records
+- Try both address families in parallel
+- Use whichever connects successfully
 
+#### Force IPv4
+If you want to force IPv4 connection (e.g., IPv6 is unavailable or unstable):
+```json
+{
+  "config": {
+    "host": "smtp.qq.com",
+    "port": 465,
+    "secure": true,
+    "localAddress": "0.0.0.0",
+    "auth": {
+      "user": "your@qq.com",
+      "pass": "authorization-code"
+    }
+  }
+}
+```
+
+#### Force IPv6
+If you want to force IPv6 connection:
+```json
+{
+  "config": {
+    "host": "smtp.example.com",
+    "port": 465,
+    "secure": true,
+    "localAddress": "::",
+    "auth": {
+      "user": "your@example.com",
+      "pass": "your-password"
+    }
+  }
+}
+```
+
+#### Use IPv6 Address as Host
+You can also use an IPv6 address directly as the host:
+```json
+{
+  "config": {
+    "host": "2001:db8::1",
+    "port": 465,
+    "secure": true,
+    "auth": {
+      "user": "your@example.com",
+      "pass": "your-password"
+    }
+  }
+}
+```
+
+### Events Configuration
+| Event | Default | Description |
+|-------|---------|-------------|
+| `created` | false | When a new session starts |
+| `idle` | true | When a session completes (AI finishes responding) |
+| `error` | true | When a session encounters an error |
+### Template Variables
 | Variable | Description | Available Events |
 |----------|-------------|------------------|
 | `{{eventType}}` | Event type (created, idle, error) | All |
@@ -99,64 +202,83 @@ Use these variables in your subject and body templates:
 | `{{message}}` | Completion message | idle |
 | `{{duration}}` | Task duration | idle |
 | `{{error}}` | Error message | error |
+## CLI Tool
+This package includes a CLI tool to test your notification channel configuration.
+### Test Command
+```bash
+# Test all channels (validates config, tests connection, sends test email)
+npx @ulthon/ul-opencode-event test
 
-## Events
+# Test a specific channel by name
+npx @ulthon/ul-opencode-event test --channel "My Email"
 
-| Event | When it triggers |
-|-------|------------------|
-| `created` | When a new session starts |
-| `idle` | When a session completes (AI finishes responding) |
-| `error` | When a session encounters an error |
+# Only verify connection without sending email
+npx @ulthon/ul-opencode-event test --no-send
+```
+### 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
 
-## Multiple Channels
+[ul-opencode-event-cli] Testing channel: "My Email"
+  Type: smtp
+  Recipients: user@example.com
 
-You can configure multiple channels, and all enabled channels will receive notifications:
+  [1/3] Validating configuration...
+  [OK] Configuration is valid
 
-```json
-{
-  "channels": [
-    {
-      "type": "smtp",
-      "enabled": true,
-      "name": "Primary Email",
-      "config": { "host": "smtp.primary.com", ... },
-      "recipients": ["primary@example.com"],
-      "events": { "created": true, "idle": true, "error": true }
-    },
-    {
-      "type": "smtp",
-      "enabled": true,
-      "name": "Secondary Email",
-      "config": { "host": "smtp.secondary.com", ... },
-      "recipients": ["secondary@example.com"],
-      "events": { "idle": true, "error": true }
-    }
-  ]
-}
-```
+  [2/3] Testing SMTP connection to smtp.example.com:465...
+  [OK] Connection successful
 
-## Troubleshooting
+  [3/3] Sending test email...
+  [OK] Test email sent successfully
+  Message ID: <xxx>
 
-### No notifications sent
+  [SUCCESS] Channel "My Email" passed all tests
 
+[ul-opencode-event-cli] Test Summary:
+  Passed: 1
+  Failed: 0
+```
+## Troubleshooting
+### SMTP connection failed
+**Q: Does this plugin support IPv4? IPv6?**
+**A: Yes, both are supported.** The plugin uses nodemailer which automatically:
+- Resolves DNS to both IPv4 (A) and IPv6 (AAAA) records
+- Tries both address families in parallel
+- Falls back if one fails
+**Common issues:**
+1. **Wrong password**: Use authorization code for QQ/163, App Password for Gmail
+2. **Wrong port**: Use 465 for SSL, 587 for STARTTLS
+3. **Firewall**: Ensure outbound connections to SMTP port are allowed
+4. **IPv6 issues**: If your network has incomplete IPv6, connections may timeout
+   - Check your network's IPv6 configuration
+   - Contact your network administrator if needed
+### Debug mode
+```bash
+# Enable debug logging
+UL_OPENCODE_EVENT_DEBUG=1 npx @ulthon/ul-opencode-event test
+```
+### No notifications sent
 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
+4. Ensure config file exists at correct location
+## Local Development
+```bash
+# Build
+npm run build
 
-### SMTP authentication failed
+# Test locally without publishing
+node dist/cli.js test
 
-- For Gmail, use an App Password instead of your regular password
-- For QQ Mail, use the authorization code
-- Ensure `secure` matches your port (465 = true, 587 = false)
+# Or use npm link
+npm link
+npx @ulthon/ul-opencode-event test
 
+# Unlink when done
+npm unlink -g @ulthon/ul-opencode-event
+```
 ## License
-
 MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,473 @@
+#!/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';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const CLI_PREFIX = '[ul-opencode-event-cli]';
+const LOOKUP_TIMEOUT_MS = 1200;
+/**
+ * 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
+ * Supports IPv4/IPv6 via localAddress option
+ */
+function createTransporter(channel, hostOverride) {
+    const config = channel.config;
+    const host = hostOverride || config.host;
+    const transportOptions = {
+        host,
+        port: config.port,
+        secure: config.secure ?? (config.port === 465),
+        auth: {
+            user: config.auth.user,
+            pass: config.auth.pass,
+        },
+    };
+    // Add localAddress for IPv4/IPv6 control
+    // - "0.0.0.0" or specific IPv4 to force IPv4
+    // - "::" or specific IPv6 to force IPv6
+    if (config.localAddress) {
+        transportOptions.localAddress = config.localAddress;
+    }
+    if (hostOverride && hostOverride !== config.host) {
+        transportOptions.tls = {
+            servername: config.host,
+        };
+    }
+    return nodemailer.createTransport(transportOptions);
+}
+function shouldRetryWithLookup(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes('querya etimeout') ||
+        normalized.includes('queryaaaa etimeout') ||
+        normalized.includes('enotfound') ||
+        normalized.includes('eai_again'));
+}
+async function resolveHostViaLookup(host) {
+    if (isIP(host) !== 0) {
+        return host;
+    }
+    const withTimeout = (task, timeoutMs) => {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`lookup timeout after ${timeoutMs}ms`)), timeoutMs);
+            task.then(value => {
+                clearTimeout(timer);
+                resolve(value);
+            }, error => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    };
+    try {
+        const addr = await withTimeout(lookup(host, { family: 4 }), LOOKUP_TIMEOUT_MS);
+        return addr.address;
+    }
+    catch { }
+    try {
+        const addr = await withTimeout(lookup(host, { family: 6 }), LOOKUP_TIMEOUT_MS);
+        return addr.address;
+    }
+    catch { }
+    return null;
+}
+/**
+ * Test SMTP connection
+ */
+async function testConnection(channel) {
+    const config = channel.config;
+    const preResolvedHost = await resolveHostViaLookup(config.host);
+    if (preResolvedHost && preResolvedHost !== config.host) {
+        try {
+            const preResolvedTransporter = createTransporter(channel, preResolvedHost);
+            await preResolvedTransporter.verify();
+            return {
+                success: true,
+                info: `DNS pre-resolved: ${config.host} -> ${preResolvedHost}`,
+            };
+        }
+        catch (preResolveError) {
+            const preResolveMessage = preResolveError instanceof Error ? preResolveError.message : String(preResolveError);
+            try {
+                const transporter = createTransporter(channel);
+                await transporter.verify();
+                return {
+                    success: true,
+                    info: `DNS pre-resolve verify failed (${preResolveMessage}), hostname verify succeeded`,
+                };
+            }
+            catch (hostError) {
+                const hostMessage = hostError instanceof Error ? hostError.message : String(hostError);
+                return { success: false, error: `${preResolveMessage}; hostname verify failed: ${hostMessage}` };
+            }
+        }
+    }
+    try {
+        const transporter = createTransporter(channel);
+        await transporter.verify();
+        return { success: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!shouldRetryWithLookup(message)) {
+            return { success: false, error: message };
+        }
+        const resolvedHost = await resolveHostViaLookup(config.host);
+        if (!resolvedHost) {
+            return { success: false, error: `${message}; lookup() fallback failed for ${config.host}` };
+        }
+        try {
+            const fallbackTransporter = createTransporter(channel, resolvedHost);
+            await fallbackTransporter.verify();
+            return {
+                success: true,
+                info: `DNS fallback used: ${config.host} -> ${resolvedHost}`,
+            };
+        }
+        catch (fallbackError) {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            return { success: false, error: `${message}; fallback verify failed: ${fallbackMessage}` };
+        }
+    }
+}
+/**
+ * Send test email
+ */
+async function sendTestEmail(channel) {
+    const config = channel.config;
+    const fromName = channel.name || 'OpenCode Notification Test';
+    const timestamp = new Date().toISOString();
+    const mailOptions = {
+        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>
+      `,
+    };
+    const preResolvedHost = await resolveHostViaLookup(config.host);
+    if (preResolvedHost && preResolvedHost !== config.host) {
+        try {
+            const preResolvedTransporter = createTransporter(channel, preResolvedHost);
+            const result = await preResolvedTransporter.sendMail(mailOptions);
+            return {
+                success: true,
+                messageId: result.messageId,
+                info: `DNS pre-resolved: ${config.host} -> ${preResolvedHost}`,
+            };
+        }
+        catch (preResolveError) {
+            const preResolveMessage = preResolveError instanceof Error ? preResolveError.message : String(preResolveError);
+            try {
+                const transporter = createTransporter(channel);
+                const result = await transporter.sendMail(mailOptions);
+                return {
+                    success: true,
+                    messageId: result.messageId,
+                    info: `DNS pre-resolve send failed (${preResolveMessage}), hostname send succeeded`,
+                };
+            }
+            catch (hostError) {
+                const hostMessage = hostError instanceof Error ? hostError.message : String(hostError);
+                return { success: false, error: `${preResolveMessage}; hostname send failed: ${hostMessage}` };
+            }
+        }
+    }
+    try {
+        const transporter = createTransporter(channel);
+        const result = await transporter.sendMail(mailOptions);
+        return { success: true, messageId: result.messageId };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!shouldRetryWithLookup(message)) {
+            return { success: false, error: message };
+        }
+        const resolvedHost = await resolveHostViaLookup(config.host);
+        if (!resolvedHost) {
+            return { success: false, error: `${message}; lookup() fallback failed for ${config.host}` };
+        }
+        try {
+            const fallbackTransporter = createTransporter(channel, resolvedHost);
+            const result = await fallbackTransporter.sendMail(mailOptions);
+            return {
+                success: true,
+                messageId: result.messageId,
+                info: `DNS fallback used: ${config.host} -> ${resolvedHost}`,
+            };
+        }
+        catch (fallbackError) {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            return { success: false, error: `${message}; fallback send failed: ${fallbackMessage}` };
+        }
+    }
+}
+/**
+ * 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`);
+    if (connectionResult.info) {
+        console.log(`  [INFO] ${connectionResult.info}`);
+    }
+    // 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`);
+    if (sendResult.info) {
+        console.log(`  [INFO] ${sendResult.info}`);
+    }
+    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/email.js

@@ -2,6 +2,44 @@
  * Email sender module for SMTP-based notifications
  */
 import * as nodemailer from 'nodemailer';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const LOOKUP_TIMEOUT_MS = 1200;
+function shouldRetryWithLookup(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes('querya etimeout') ||
+        normalized.includes('queryaaaa etimeout') ||
+        normalized.includes('enotfound') ||
+        normalized.includes('eai_again'));
+}
+async function resolveHostViaLookup(host) {
+    if (isIP(host) !== 0) {
+        return host;
+    }
+    const withTimeout = (task, timeoutMs) => {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error(`lookup timeout after ${timeoutMs}ms`)), timeoutMs);
+            task.then(value => {
+                clearTimeout(timer);
+                resolve(value);
+            }, error => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    };
+    try {
+        const addr = await withTimeout(lookup(host, { family: 4 }), LOOKUP_TIMEOUT_MS);
+        return addr.address;
+    }
+    catch { }
+    try {
+        const addr = await withTimeout(lookup(host, { family: 6 }), LOOKUP_TIMEOUT_MS);
+        return addr.address;
+    }
+    catch { }
+    return null;
+}
 /**
  * Creates an email sender for the given SMTP channel
  * @param channel - The channel configuration (must be SMTP type)
@@ -22,31 +60,65 @@ export function createEmailSender(channel) {
     }
     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);
+    const createTransport = (hostOverride) => {
+        const host = hostOverride || config.host;
+        const transportOptions = {
+            host,
+            port: config.port,
+            secure: config.secure,
+            auth: {
+                user: config.auth.user,
+                pass: config.auth.pass,
+            },
+        };
+        if (config.localAddress) {
+            transportOptions.localAddress = config.localAddress;
+        }
+        if (hostOverride && hostOverride !== config.host) {
+            transportOptions.tls = {
+                servername: config.host,
+            };
+        }
+        const transport = nodemailer.createTransport(transportOptions);
+        transport.set('disableFileAccess', true);
+        transport.set('disableUrlAccess', true);
+        return transport;
+    };
     return {
         async send(subject, body) {
+            const mailOptions = {
+                from: `"${fromName}" <${config.auth.user}>`,
+                to: channel.recipients.join(', '),
+                subject,
+                html: body,
+                text: body,
+            };
+            const preResolvedHost = await resolveHostViaLookup(config.host);
+            if (preResolvedHost && preResolvedHost !== config.host) {
+                try {
+                    const preResolvedTransport = createTransport(preResolvedHost);
+                    await preResolvedTransport.sendMail(mailOptions);
+                    return;
+                }
+                catch { }
+            }
             try {
-                await transport.sendMail({
-                    from: `"${fromName}" <${config.auth.user}>`,
-                    to: channel.recipients.join(', '),
-                    subject,
-                    html: body,
-                    text: body,
-                });
+                const transport = createTransport();
+                await transport.sendMail(mailOptions);
             }
             catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (shouldRetryWithLookup(message)) {
+                    const resolvedHost = await resolveHostViaLookup(config.host);
+                    if (resolvedHost) {
+                        try {
+                            const fallbackTransport = createTransport(resolvedHost);
+                            await fallbackTransport.sendMail(mailOptions);
+                            return;
+                        }
+                        catch { }
+                    }
+                }
                 // Silent failure: log error but don't throw
                 const timestamp = new Date().toISOString();
                 console.error(`[${timestamp}] [${fromName}] Failed to send email:`, error);

package/dist/types.d.ts

@@ -36,6 +36,13 @@ export interface SMTPConfig {
     host: string;
     port: number;
     secure?: boolean;
+    /**
+     * Local interface to bind for outgoing connections
+     * - Use IPv4 address (e.g., "0.0.0.0", "192.168.1.1") to force IPv4
+     * - Use IPv6 address (e.g., "::", "::1", "2001:db8::1") to force IPv6
+     * - If not specified, both IPv4 and IPv6 are tried automatically
+     */
+    localAddress?: string;
     auth: {
         user: string;
         pass: string;

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@ulthon/ul-opencode-event",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "OpenCode notification plugin - sends email when session events occur",
   "author": "augushong",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "ul-opencode-event": "dist/cli.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -26,7 +29,8 @@
     "plugin",
     "notification",
     "email",
-    "smtp"
+    "smtp",
+    "cli"
   ],
   "files": [
     "dist",