@julioventura/opensquad 0.1.17

package/skills/smtp-sender/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: smtp-sender
+description: >
+  Send HTML plus plain-text emails through a native SMTP connection using local .env credentials.
+  Useful when a squad needs direct SMTP delivery without relying on an external email API.
+description_pt-BR: >
+  Envia emails HTML e texto puro por conexao SMTP nativa usando credenciais locais do .env.
+  Util quando um squad precisa de entrega SMTP direta sem depender de uma API externa.
+description_es: >
+  Envia correos HTML y texto plano mediante una conexion SMTP nativa usando credenciales locales del .env.
+  Util cuando un squad necesita entrega SMTP directa sin depender de una API externa.
+type: script
+version: "1.0.0"
+script:
+  path: scripts/send.js
+  runtime: node
+  invoke: "node --env-file=.env {skill_path}/scripts/send.js --html \"{html}\" --text \"{text}\" --newsletter-preview \"{newsletter_preview}\" --preview \"{send_preview}\" --output \"{output}\" --smtp-host-env \"{smtp_host_env}\" --smtp-port-env \"{smtp_port_env}\" --smtp-user-env \"{smtp_user_env}\" --smtp-pass-env \"{smtp_pass_env}\""
+env:
+  - SMTP_HOST
+  - SMTP_PORT
+  - SMTP_USER
+  - SMTP_PASS
+categories: [email, smtp, automation]
+---
+
+# SMTP Sender
+
+## When to use
+
+Use this skill when a squad already has the final `newsletter.html` and `newsletter.txt` files and needs to deliver them through a direct SMTP server such as a brand-owned mailbox.
+
+## Workflow
+
+1. Confirm the final send metadata in `send-preview.md` and `newsletter-preview.md`.
+2. Run the sender script with the HTML file, text file, preview files, and output path.
+3. Pass the brand-specific SMTP env keys explicitly when the workspace serves multiple brands, or persist them in `send-preview.md` so the sender can resolve them automatically.
+4. Read `email-send-result.md` after the command finishes and confirm status, message ID, sender, and audience.
+
+## Command
+
+```bash
+node --env-file=.env {skill_path}/scripts/send.js \
+  --html "squads/jornal-matutino/output/2026-05-18-201500/newsletter.html" \
+  --text "squads/jornal-matutino/output/2026-05-18-201500/newsletter.txt" \
+  --newsletter-preview "squads/jornal-matutino/output/2026-05-18-201500/newsletter-preview.md" \
+  --preview "squads/jornal-matutino/output/2026-05-18-201500/send-preview.md" \
+  --output "squads/jornal-matutino/output/2026-05-18-201500/email-send-result.md"
+```
+
+When `send-preview.md` does not include the SMTP env key mapping, append the brand-specific overrides explicitly:
+
+```bash
+  --smtp-host-env "BRAND_SMTP_HOST" \
+  --smtp-port-env "BRAND_SMTP_PORT" \
+  --smtp-user-env "BRAND_SMTP_USER" \
+  --smtp-pass-env "BRAND_SMTP_PASS"
+```
+
+## Output
+
+The script writes `email-send-result.md` in this format:
+
+```markdown
+# Email Send Result
+
+**Status:** sent | failed
+**Mode:** test | live
+**Provider:** SMTP
+**Message ID:** ...
+**From:** ...
+**To/Audience:** ...
+**Scheduled at:** ...
+**Sent at:** ...
+**Notes:** ...
+```
+
+## Constraints
+
+- Current native flow supports immediate `test` and `live` sends.
+- `scheduled` mode is not implemented in the local SMTP sender.
+- The sender always opens a secure `SSL/TLS` SMTP connection.
+- If `send-preview.md` contains `SMTP Host Env`, `SMTP Port Env`, `SMTP User Env`, and `SMTP Pass Env`, those mappings are used automatically.
+
+## Available operations
+
+- **Send multipart email** -- Deliver HTML plus plain-text content over SMTP
+- **Brand env mapping** -- Use explicit env key names for multi-brand workspaces
+- **Delivery logging** -- Persist the provider result to `email-send-result.md`

package/skills/smtp-sender/scripts/send.js

@@ -0,0 +1,478 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+import tls from 'node:tls';
+import { dirname, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ENV_KEYS = {
+  smtpHost: 'SMTP_HOST',
+  smtpPort: 'SMTP_PORT',
+  smtpUser: 'SMTP_USER',
+  smtpPass: 'SMTP_PASS',
+};
+
+function stripWrapping(value) {
+  return value
+    .replace(/^[<'"`]+/, '')
+    .replace(/[>'"`]+$/, '')
+    .trim();
+}
+
+function normalizeLineEndings(value) {
+  return value.replace(/\r?\n/g, '\r\n');
+}
+
+export function parseArgs(argv) {
+  const args = {
+    htmlPath: '',
+    textPath: '',
+    newsletterPreviewPath: '',
+    previewPath: '',
+    outputPath: '',
+    subject: '',
+    from: '',
+    to: '',
+    replyTo: '',
+    mode: '',
+    scheduledAt: '',
+    smtpHostEnv: null,
+    smtpPortEnv: null,
+    smtpUserEnv: null,
+    smtpPassEnv: null,
+    dryRun: false,
+  };
+
+  for (let index = 2; index < argv.length; index++) {
+    const current = argv[index];
+
+    if (current === '--html' && index + 1 < argv.length) {
+      args.htmlPath = argv[++index];
+    } else if (current === '--text' && index + 1 < argv.length) {
+      args.textPath = argv[++index];
+    } else if (current === '--newsletter-preview' && index + 1 < argv.length) {
+      args.newsletterPreviewPath = argv[++index];
+    } else if (current === '--preview' && index + 1 < argv.length) {
+      args.previewPath = argv[++index];
+    } else if (current === '--output' && index + 1 < argv.length) {
+      args.outputPath = argv[++index];
+    } else if (current === '--subject' && index + 1 < argv.length) {
+      args.subject = argv[++index];
+    } else if (current === '--from' && index + 1 < argv.length) {
+      args.from = argv[++index];
+    } else if (current === '--to' && index + 1 < argv.length) {
+      args.to = argv[++index];
+    } else if (current === '--reply-to' && index + 1 < argv.length) {
+      args.replyTo = argv[++index];
+    } else if (current === '--mode' && index + 1 < argv.length) {
+      args.mode = argv[++index];
+    } else if (current === '--scheduled-at' && index + 1 < argv.length) {
+      args.scheduledAt = argv[++index];
+    } else if (current === '--smtp-host-env' && index + 1 < argv.length) {
+      args.smtpHostEnv = argv[++index];
+    } else if (current === '--smtp-port-env' && index + 1 < argv.length) {
+      args.smtpPortEnv = argv[++index];
+    } else if (current === '--smtp-user-env' && index + 1 < argv.length) {
+      args.smtpUserEnv = argv[++index];
+    } else if (current === '--smtp-pass-env' && index + 1 < argv.length) {
+      args.smtpPassEnv = argv[++index];
+    } else if (current === '--dry-run') {
+      args.dryRun = true;
+    }
+  }
+
+  return args;
+}
+
+export async function loadEnvVars(targetDir = process.cwd()) {
+  const envVars = { ...process.env };
+
+  try {
+    const raw = await readFile(resolve(targetDir, '.env'), 'utf-8');
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const separatorIndex = trimmed.indexOf('=');
+      if (separatorIndex === -1) continue;
+      const key = trimmed.slice(0, separatorIndex).trim();
+      const value = trimmed.slice(separatorIndex + 1).trim().replace(/^['"]|['"]$/g, '');
+      if (key) {
+        envVars[key] = value;
+      }
+    }
+  } catch {
+    // Optional .env
+  }
+
+  return envVars;
+}
+
+export function resolveConfiguredEnv(env, options = {}) {
+  const smtpHostKey = options.smtpHostEnv || DEFAULT_ENV_KEYS.smtpHost;
+  const smtpPortKey = options.smtpPortEnv || DEFAULT_ENV_KEYS.smtpPort;
+  const smtpUserKey = options.smtpUserEnv || DEFAULT_ENV_KEYS.smtpUser;
+  const smtpPassKey = options.smtpPassEnv || DEFAULT_ENV_KEYS.smtpPass;
+
+  return {
+    smtpHostKey,
+    smtpPortKey,
+    smtpUserKey,
+    smtpPassKey,
+    smtpHost: env[smtpHostKey],
+    smtpPort: env[smtpPortKey],
+    smtpUser: env[smtpUserKey],
+    smtpPass: env[smtpPassKey],
+    secure: true,
+  };
+}
+
+export function parseMarkdownFields(content) {
+  const result = {};
+  const matches = content.matchAll(/^\*\*(.+?):\*\*\s*(.+)$/gm);
+  for (const match of matches) {
+    result[match[1].trim()] = stripWrapping(match[2].trim());
+  }
+  return result;
+}
+
+export function resolveSmtpEnvOptions(args, previewFields = {}) {
+  return {
+    smtpHostEnv: args.smtpHostEnv || previewFields['SMTP Host Env'] || null,
+    smtpPortEnv: args.smtpPortEnv || previewFields['SMTP Port Env'] || null,
+    smtpUserEnv: args.smtpUserEnv || previewFields['SMTP User Env'] || null,
+    smtpPassEnv: args.smtpPassEnv || previewFields['SMTP Pass Env'] || null,
+  };
+}
+
+function parseRecipients(value) {
+  return value
+    .split(/[;,\n]/)
+    .map((entry) => stripWrapping(entry.trim()))
+    .filter(Boolean);
+}
+
+function extractEmailAddress(value) {
+  const match = value.match(/<([^>]+)>/);
+  return stripWrapping(match ? match[1] : value);
+}
+
+function formatMailboxAddress(name, email) {
+  if (!name) return email;
+  return `${encodeHeader(name)} <${email}>`;
+}
+
+function encodeHeader(value) {
+  if (/^[\x20-\x7E]*$/.test(value)) return value;
+  return `=?UTF-8?B?${Buffer.from(value, 'utf8').toString('base64')}?=`;
+}
+
+function encodeBodyPart(value) {
+  return Buffer.from(normalizeLineEndings(value), 'utf8').toString('base64').replace(/.{1,76}/g, '$&\r\n').trimEnd();
+}
+
+function buildMessageHeaderId(from) {
+  const domain = (from.split('@')[1] || 'opensquad.local').replace(/[^a-z0-9.-]/gi, '') || 'opensquad.local';
+  return `<${Date.now()}.${Math.random().toString(16).slice(2)}@${domain}>`;
+}
+
+function formatUnknownError(error) {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === 'string' && error.trim()) return error;
+  if (error && typeof error === 'object') {
+    const details = [error.code, error.reason, error.name, error.command].filter(Boolean).join(' | ');
+    if (details) return details;
+
+    try {
+      const json = JSON.stringify(error);
+      if (json && json !== '{}') return json;
+    } catch {
+      // Fall through
+    }
+  }
+
+  return 'Unknown SMTP sender failure';
+}
+
+function escapeDataBody(value) {
+  return normalizeLineEndings(value).replace(/^\./gm, '..');
+}
+
+export function buildMimeMessage({ from, to, replyTo, subject, html, text }) {
+  const fromEmail = extractEmailAddress(from);
+  const boundary = `opensquad_${Date.now().toString(16)}_${Math.random().toString(16).slice(2)}`;
+  const messageHeaderId = buildMessageHeaderId(fromEmail);
+  const headers = [
+    `From: ${from}`,
+    `To: ${to.join(', ')}`,
+    replyTo ? `Reply-To: ${replyTo}` : null,
+    `Subject: ${encodeHeader(subject)}`,
+    `Message-ID: ${messageHeaderId}`,
+    `Date: ${new Date().toUTCString()}`,
+    'X-Mailer: Opensquad SMTP Sender',
+    'MIME-Version: 1.0',
+    `Content-Type: multipart/alternative; boundary="${boundary}"`,
+    '',
+    `--${boundary}`,
+    'Content-Type: text/plain; charset="UTF-8"',
+    'Content-Transfer-Encoding: base64',
+    '',
+    escapeDataBody(encodeBodyPart(text)),
+    `--${boundary}`,
+    'Content-Type: text/html; charset="UTF-8"',
+    'Content-Transfer-Encoding: base64',
+    '',
+    escapeDataBody(encodeBodyPart(html)),
+    `--${boundary}--`,
+    '',
+  ].filter((entry) => entry !== null);
+
+  return headers.join('\r\n');
+}
+
+function createResponseReader(socket) {
+  let buffer = '';
+  let currentLines = [];
+  const queue = [];
+
+  function flush(response) {
+    const next = queue.shift();
+    if (next) {
+      clearTimeout(next.timeoutId);
+      next.resolve(response);
+    }
+  }
+
+  socket.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+
+    while (buffer.includes('\n')) {
+      const newlineIndex = buffer.indexOf('\n');
+      const line = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+      buffer = buffer.slice(newlineIndex + 1);
+      if (!line) continue;
+
+      currentLines.push(line);
+      const match = line.match(/^(\d{3})([ -])(.*)$/);
+      if (!match) continue;
+      if (match[2] === ' ') {
+        const code = Number(match[1]);
+        const lines = currentLines;
+        currentLines = [];
+        flush({ code, lines, message: lines.join('\n') });
+      }
+    }
+  });
+
+  function waitForResponse(timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        const pending = queue.findIndex((entry) => entry.timeoutId === timeoutId);
+        if (pending !== -1) queue.splice(pending, 1);
+        reject(new Error(`SMTP response timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      queue.push({ resolve, reject, timeoutId });
+    });
+  }
+
+  return { waitForResponse };
+}
+
+async function connectSmtp({ host, port, secure }) {
+  return new Promise((resolve, reject) => {
+    const options = { host, port, servername: host, family: 4 };
+    const socket = secure
+      ? tls.connect(options, () => resolve(socket))
+      : net.createConnection({ host, port }, () => resolve(socket));
+
+    socket.once('error', reject);
+  });
+}
+
+async function sendCommand(socket, reader, command, expectedCodes) {
+  if (command != null) {
+    socket.write(`${command}\r\n`);
+  }
+  const response = await reader.waitForResponse();
+  if (expectedCodes && !expectedCodes.includes(response.code)) {
+    throw new Error(`SMTP command failed for '${command ?? '[initial]'}': ${response.message}`);
+  }
+  return response;
+}
+
+function extractProviderMessageId(response) {
+  const match = response.message.match(/\bid=([^\s]+)/i);
+  return match ? match[1] : 'not-returned';
+}
+
+export async function sendViaSmtp({ host, port, secure, username, password, from, to, message }) {
+  const socket = await connectSmtp({ host, port, secure });
+  const reader = createResponseReader(socket);
+
+  try {
+    await sendCommand(socket, reader, null, [220]);
+    await sendCommand(socket, reader, 'EHLO opensquad.local', [250]);
+    await sendCommand(socket, reader, 'AUTH LOGIN', [334]);
+    await sendCommand(socket, reader, Buffer.from(username, 'utf8').toString('base64'), [334]);
+    await sendCommand(socket, reader, Buffer.from(password, 'utf8').toString('base64'), [235]);
+    await sendCommand(socket, reader, `MAIL FROM:<${from}>`, [250]);
+    for (const recipient of to) {
+      await sendCommand(socket, reader, `RCPT TO:<${recipient}>`, [250, 251]);
+    }
+    await sendCommand(socket, reader, 'DATA', [354]);
+    socket.write(`${message}\r\n.\r\n`);
+    const deliveryResponse = await reader.waitForResponse();
+    if (deliveryResponse.code !== 250) {
+      throw new Error(`SMTP delivery failed: ${deliveryResponse.message}`);
+    }
+    await sendCommand(socket, reader, 'QUIT', [221]);
+    socket.end();
+
+    return {
+      messageId: extractProviderMessageId(deliveryResponse),
+      response: deliveryResponse.message,
+    };
+  } catch (error) {
+    socket.destroy();
+    throw error;
+  }
+}
+
+export function buildEmailSendResult({ status, mode, messageId, from, to, scheduledAt, sentAt, notes }) {
+  return [
+    '# Email Send Result',
+    '',
+    `**Status:** ${status}`,
+    `**Mode:** ${mode}`,
+    '**Provider:** SMTP',
+    `**Message ID:** ${messageId}`,
+    `**From:** ${from}`,
+    `**To/Audience:** ${to.join(', ')}`,
+    `**Scheduled at:** ${scheduledAt || 'not scheduled'}`,
+    `**Sent at:** ${sentAt}`,
+    `**Notes:** ${notes}`,
+    '',
+  ].join('\n');
+}
+
+async function writeResult(outputPath, content) {
+  const absoluteOutputPath = resolve(outputPath);
+  await mkdir(dirname(absoluteOutputPath), { recursive: true });
+  await writeFile(absoluteOutputPath, content, 'utf8');
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.htmlPath || !args.textPath || !args.newsletterPreviewPath || !args.previewPath || !args.outputPath) {
+    throw new Error('Missing required arguments. Use --html, --text, --newsletter-preview, --preview, and --output.');
+  }
+
+  const [html, text, newsletterPreview, sendPreview] = await Promise.all([
+    readFile(resolve(args.htmlPath), 'utf8'),
+    readFile(resolve(args.textPath), 'utf8'),
+    readFile(resolve(args.newsletterPreviewPath), 'utf8'),
+    readFile(resolve(args.previewPath), 'utf8'),
+  ]);
+
+  const newsletterFields = parseMarkdownFields(newsletterPreview);
+  const previewFields = parseMarkdownFields(sendPreview);
+  const env = await loadEnvVars();
+  const smtpEnvOptions = resolveSmtpEnvOptions(args, previewFields);
+  const configuredEnv = resolveConfiguredEnv(env, smtpEnvOptions);
+
+  const subject = args.subject || newsletterFields.Subject;
+  const senderName = stripWrapping(newsletterFields.Brand || previewFields['Sender Name'] || '');
+  const fromEmail = extractEmailAddress(stripWrapping(args.from || previewFields.From || configuredEnv.smtpUser || ''));
+  const from = formatMailboxAddress(senderName, fromEmail);
+  const recipients = parseRecipients(args.to || previewFields.To || '');
+  const replyTo = stripWrapping(args.replyTo || '');
+  const mode = stripWrapping(args.mode || previewFields.Mode || 'test').toLowerCase();
+  const scheduledAt = stripWrapping(args.scheduledAt || previewFields['Scheduled at'] || 'not scheduled');
+  const secure = configuredEnv.secure;
+
+  if (!subject) throw new Error('Missing subject. Provide --subject or ensure newsletter-preview.md includes **Subject:**.');
+  if (!fromEmail) throw new Error('Missing sender. Provide --from or ensure send-preview.md includes **From:**.');
+  if (recipients.length === 0) throw new Error('Missing recipients. Provide --to or ensure send-preview.md includes **To:**.');
+  if (mode === 'scheduled') throw new Error('Scheduled mode is not implemented in the native SMTP sender.');
+  if (!configuredEnv.smtpHost || !configuredEnv.smtpPort || !configuredEnv.smtpUser || !configuredEnv.smtpPass) {
+    throw new Error(
+      `Missing SMTP configuration. Checked ${configuredEnv.smtpHostKey}, ${configuredEnv.smtpPortKey}, ${configuredEnv.smtpUserKey}, ${configuredEnv.smtpPassKey}.`
+    );
+  }
+
+  const sentAt = new Date().toISOString();
+
+  try {
+    if (args.dryRun) {
+      const result = buildEmailSendResult({
+        status: 'sent',
+        mode,
+        messageId: 'dry-run',
+        from,
+        to: recipients,
+        scheduledAt,
+        sentAt,
+        notes: `Dry run only. SMTP connection not opened. Expected server ${configuredEnv.smtpHost}:${configuredEnv.smtpPort}.`,
+      });
+      await writeResult(args.outputPath, result);
+      return;
+    }
+
+    const message = buildMimeMessage({
+      from,
+      to: recipients,
+      replyTo,
+      subject,
+      html,
+      text,
+    });
+
+    const delivery = await sendViaSmtp({
+      host: configuredEnv.smtpHost,
+      port: Number(configuredEnv.smtpPort),
+      secure,
+      username: configuredEnv.smtpUser,
+      password: configuredEnv.smtpPass,
+      from: fromEmail,
+      to: recipients,
+      message,
+    });
+
+    const result = buildEmailSendResult({
+      status: 'sent',
+      mode,
+      messageId: delivery.messageId,
+      from,
+      to: recipients,
+      scheduledAt,
+      sentAt,
+      notes: `Accepted by SMTP server ${configuredEnv.smtpHost}:${configuredEnv.smtpPort}. ${delivery.response}`,
+    });
+    await writeResult(args.outputPath, result);
+    console.log(`SMTP send accepted with message ID ${delivery.messageId}`);
+  } catch (error) {
+    const errorMessage = formatUnknownError(error);
+    const result = buildEmailSendResult({
+      status: 'failed',
+      mode,
+      messageId: 'not-returned',
+      from,
+      to: recipients,
+      scheduledAt,
+      sentAt,
+      notes: errorMessage,
+    });
+    await writeResult(args.outputPath, result);
+    throw new Error(errorMessage);
+  }
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((error) => {
+    console.error(`\n❌ ${formatUnknownError(error)}`);
+    process.exit(1);
+  });
+}