stellamail 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smart Choice Inspections LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# ✉️ Stellamail
+
+**Safe email CLI for AI agents and humans.**
+
+Built with safety rails that prevent the disasters AI agents cause with email — duplicate sends, missing attachments, forgotten CCs. Works great as a standalone terminal email client too.
+
+## Install
+
+```bash
+npm install -g stellamail
+```
+
+## Quick Start
+
+```bash
+# Interactive setup wizard
+stellamail init
+
+# Check your inbox
+stellamail inbox --account work
+
+# Send an email
+stellamail send --account work \
+  --to "client@example.com" \
+  --cc "boss@example.com" \
+  --subject "Report attached" \
+  --body "Hi, please find your report attached." \
+  --attachment "/path/to/report.pdf"
+
+# Read a message
+stellamail read 42 --account work
+
+# Reply
+stellamail reply 42 --account work --body "Thanks for the update!"
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `send` | Send an email |
+| `reply <id>` | Reply to an email |
+| `forward <id>` | Forward an email |
+| `inbox` | List inbox messages |
+| `read <id>` | Read a single email |
+| `search` | Search emails |
+| `folders` | List mailbox folders |
+| `move <id>` | Move a message to another folder |
+| `delete <id>` | Delete a message |
+| `flag <id>` | Toggle flags on a message |
+| `log` | View send log |
+| `test` | Test SMTP/IMAP connections |
+| `accounts` | List configured accounts |
+| `templates` | List available templates |
+| `init` | Interactive setup wizard |
+
+## Safety Features
+
+These aren't optional — they're the whole point.
+
+- 🔒 **Duplicate blocking** — Same email within 24h? Blocked. Configurable cooldown.
+- ✅ **Attachment validation** — PDF header check, file exists, size limits.
+- 📋 **CC enforcement** — Per-account. Can't "forget" to CC the boss.
+- 📝 **Send logging** — Every send logged with timestamp, recipient, status.
+- 🚫 **One attempt only** — No retries. Ever. Fail = report and stop.
+- 🧪 **Dry run** — Preview everything before sending with `--dry-run`.
+
+## Templates
+
+Define reusable email templates in your config:
+
+```bash
+stellamail send --account work \
+  --template report-delivery \
+  --var firstName=Sarah \
+  --var reportType=Radon \
+  --var address="123 Main St" \
+  --attachment report.pdf
+```
+
+## Signatures
+
+Per-account signatures with template variables:
+
+```json
+{
+  "signature": {
+    "text": "\n--\n{{name}}\n{{title}}\n{{company}}",
+    "vars": {
+      "name": "Jane Smith",
+      "title": "Inspector",
+      "company": "Acme Inspections"
+    }
+  }
+}
+```
+
+Skip with `--no-signature`.
+
+## JSON Output
+
+Every command supports `--output json` for scripting and AI agent integration:
+
+```bash
+stellamail inbox --account work --output json
+stellamail accounts --output json
+```
+
+## Configuration
+
+Run `stellamail init` for interactive setup, or create `~/.stellamail.config.json` manually. See [config-example.json](config-example.json) for all options.
+
+**Security:**
+- Config file auto-set to `chmod 600`
+- Warning if permissions are too open
+- Environment variable override: `STELLAMAIL_ACCOUNTNAME_PASS`
+
+## Why Stellamail?
+
+An AI agent sent 15 duplicate emails to a client at midnight. The home inspector woke up to an inbox full of angry replies. That's why.
+
+Stellamail was born out of pure frustration — built by [Leo Betancor](https://makeasmartchoice.us), a New Jersey home inspector who just wanted his AI assistant to send one email. ONE. Instead, it sent fifteen. So he built an email tool his bots literally can't break.
+
+Duplicate blocking, attachment validation, and CC enforcement aren't features — they're therapy.
+
+But it's also just a really nice terminal email client for humans. Color-coded inbox, clean formatting, fast IMAP. No Electron, no bloat, no nonsense.
+
+## Tech
+
+- **SMTP:** nodemailer
+- **IMAP:** imapflow
+- **Parsing:** mailparser
+- **UI:** chalk + cli-table3
+- **Config:** JSON (no database)
+- **Runtime:** Node.js (CommonJS)
+
+## License
+
+MIT

package/bin/stellamail.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../src/cli');
+
+run().catch(err => {
+  const chalk = require('chalk');
+  console.error(chalk.red('❌ ' + err.message));
+  process.exit(1);
+});

package/config-example.json

@@ -0,0 +1,76 @@
+{
+  "_comment": "Stellamail config — copy to stellamail.config.json and fill in your details",
+
+  "smtp": {
+    "host": "smtp.example.com",
+    "port": 465,
+    "secure": true,
+    "rejectUnauthorized": false
+  },
+
+  "accounts": {
+    "work": {
+      "from": "\"Your Name\" <you@example.com>",
+      "smtp": {
+        "user": "you@example.com",
+        "pass": "your-password-here"
+      },
+      "requireCc": true,
+      "signature": {
+        "text": "\n--\n{{name}}\n{{title}}\n{{company}}\nPhone: {{phone}}",
+        "html": "<br><hr><b>{{name}}</b><br>{{title}}<br>{{company}}<br>Phone: {{phone}}",
+        "vars": {
+          "name": "Your Name",
+          "title": "Your Title",
+          "company": "Your Company",
+          "phone": "(555) 123-4567"
+        }
+      }
+    },
+    "support": {
+      "from": "\"Support\" <support@example.com>",
+      "smtp": {
+        "user": "support@example.com",
+        "pass": "your-password-here"
+      },
+      "requireCc": false
+    }
+  },
+
+  "signature": {
+    "_comment": "Global fallback signature (used when account has no signature)",
+    "text": "\n--\nSent via Stellamail",
+    "html": "<br><hr><small>Sent via Stellamail</small>"
+  },
+
+  "templates": {
+    "report-delivery": {
+      "subject": "{{reportType}} Report - {{address}}",
+      "body": "Hi {{firstName}},\n\nPlease find attached your {{reportType}} Report for {{address}}.\n\nPlease let us know if you have any questions.",
+      "cc": "inspector@example.com"
+    },
+    "invoice": {
+      "subject": "Invoice - {{invoiceNumber}}",
+      "body": "Hi {{firstName}},\n\nPlease find your invoice #{{invoiceNumber}} attached.\n\nPayment is due within 30 days.\n\nThank you for your business."
+    },
+    "follow-up": {
+      "subject": "Following up - {{topic}}",
+      "body": "Hi {{firstName}},\n\nJust following up regarding {{topic}}.\n\nPlease let me know if you have any questions."
+    }
+  },
+
+  "duplicateCheck": {
+    "cooldownSeconds": 86400,
+    "lockDir": "~/.stellamail-locks"
+  },
+
+  "attachments": {
+    "maxSizeMB": 25,
+    "validatePdf": true
+  },
+
+  "logging": {
+    "file": "~/.stellamail-log.json",
+    "maxEntries": 500
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "stellamail",
+  "version": "1.0.0",
+  "description": "Safe email CLI for AI agents and humans. Built by a fed-up home inspector whose AI assistant sent 15 duplicate emails to a client. Never again. Duplicate blocking, attachment validation, CC enforcement, templates, and a color-coded terminal UI.",
+  "bin": {
+    "stellamail": "./bin/stellamail.js"
+  },
+  "keywords": [
+    "email",
+    "cli",
+    "imap",
+    "smtp",
+    "mail",
+    "terminal",
+    "ai-agent",
+    "openclaw",
+    "nodemailer",
+    "safe-email"
+  ],
+  "author": "Smart Choice Inspections",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smartchoiceinspections/stellamail"
+  },
+  "homepage": "https://github.com/smartchoiceinspections/stellamail#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "config-example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "nodemailer": "^6.9.0",
+    "imapflow": "^1.0.0",
+    "mailparser": "^3.6.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const { findConfig } = require('./config');
+const { chalk } = require('./format');
+const Table = require('cli-table3');
+const { version } = require('../package.json');
+
+const COMMANDS = {
+  send: './commands/send',
+  inbox: './commands/inbox',
+  read: './commands/read',
+  search: './commands/search',
+  folders: './commands/folders',
+  log: './commands/log',
+  test: './commands/test',
+  accounts: './commands/accounts',
+  templates: './commands/templates',
+  reply: './commands/reply',
+  forward: './commands/forward',
+  move: './commands/move',
+  delete: './commands/delete',
+  flag: './commands/flag'
+};
+
+const ALL_COMMANDS = Object.keys(COMMANDS).concat('init', 'help', 'version');
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function suggestCommand(input) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of ALL_COMMANDS) {
+    const dist = levenshtein(input.toLowerCase(), cmd);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = cmd;
+    }
+  }
+  return bestDist <= 3 ? best : null;
+}
+
+function parseArgs(args) {
+  const opts = { attachments: [], _positional: [] };
+
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith('--')) {
+      opts._positional.push(args[i]);
+      continue;
+    }
+    const key = args[i].slice(2);
+
+    // Boolean flags
+    if (['dry-run', 'no-signature', 'html', 'no-duplicate-check', 'help',
+         'unread', 'has-attachment', 'raw', 'all', 'permanent', 'version'].includes(key)) {
+      opts[key] = true;
+      continue;
+    }
+
+    const val = args[i + 1];
+    i++;
+
+    if (key === 'attachment') {
+      opts.attachments.push(val);
+      continue;
+    }
+
+    if (key === 'var') {
+      if (!opts.vars) opts.vars = {};
+      const eq = val.indexOf('=');
+      if (eq > 0) {
+        opts.vars[val.slice(0, eq)] = val.slice(eq + 1);
+      }
+      continue;
+    }
+
+    opts[key] = val;
+  }
+
+  return opts;
+}
+
+function showBanner() {
+  const banner = new Table({
+    colWidths: [43],
+    style: { head: [], border: ['cyan'] },
+    chars: {
+      'top': '─', 'top-mid': '', 'top-left': '┌', 'top-right': '┐',
+      'bottom': '─', 'bottom-mid': '', 'bottom-left': '└', 'bottom-right': '┘',
+      'left': '│', 'left-mid': '', 'mid': '', 'mid-mid': '',
+      'right': '│', 'right-mid': '', 'middle': ''
+    }
+  });
+  banner.push(
+    [{ content: chalk.bold(`        ✉️  Stellamail v${version}`), hAlign: 'center' }],
+    [{ content: chalk.white('  Safe email CLI for AI agents & humans'), hAlign: 'center' }]
+  );
+  console.log(banner.toString());
+}
+
+function showHelp(commandName) {
+  if (commandName === 'init') {
+    const init = require('./commands/init');
+    console.log(init.help);
+    return;
+  }
+  if (commandName && COMMANDS[commandName]) {
+    const cmd = require(COMMANDS[commandName]);
+    console.log(cmd.help || `No help available for "${commandName}".`);
+    return;
+  }
+
+  showBanner();
+
+  console.log(`
+${chalk.yellow.bold('USAGE:')}
+  stellamail <command> [options]
+
+${chalk.yellow.bold('COMMANDS:')}
+  ${chalk.cyan.bold('send')}           Send an email
+  ${chalk.cyan.bold('reply')} ${chalk.red('<id>')}     Reply to an email
+  ${chalk.cyan.bold('forward')} ${chalk.red('<id>')}   Forward an email
+  ${chalk.cyan.bold('inbox')}          List inbox messages (IMAP)
+  ${chalk.cyan.bold('read')} ${chalk.red('<id>')}      Read a single email (IMAP)
+  ${chalk.cyan.bold('search')}         Search emails (IMAP)
+  ${chalk.cyan.bold('folders')}        List mailbox folders (IMAP)
+  ${chalk.cyan.bold('move')} ${chalk.red('<id>')}      Move a message to another folder
+  ${chalk.cyan.bold('delete')} ${chalk.red('<id>')}    Delete a message
+  ${chalk.cyan.bold('flag')} ${chalk.red('<id>')}      Toggle flags on a message
+  ${chalk.cyan.bold('log')}            View send log
+  ${chalk.cyan.bold('test')}           Test SMTP/IMAP connections
+  ${chalk.cyan.bold('accounts')}       List configured accounts
+  ${chalk.cyan.bold('templates')}      List available templates
+  ${chalk.cyan.bold('init')}           Interactive setup wizard
+  ${chalk.cyan.bold('help')} ${chalk.gray('[cmd]')}    Show help for a command
+
+${chalk.yellow.bold('GLOBAL OPTIONS:')}
+  ${chalk.gray('--config <path>')}     Path to stellamail.config.json
+  ${chalk.gray('--output json')}       Output as JSON (clean, no formatting)
+  ${chalk.gray('--version')}           Show version number
+
+${chalk.yellow.bold('EXAMPLES:')}
+  ${chalk.green('stellamail send --account work --to user@example.com --subject "Hello" --body "Hi there"')}
+  ${chalk.green('stellamail reply 42 --account work --body "Thanks!"')}
+  ${chalk.green('stellamail forward 42 --account work --to colleague@example.com')}
+  ${chalk.green('stellamail move 42 --account work --to Archive')}
+  ${chalk.green('stellamail delete 42 --account work')}
+  ${chalk.green('stellamail flag 42 --account work --add flagged')}
+  ${chalk.green('stellamail inbox --account work --unread')}
+  ${chalk.green('stellamail accounts --output json')}
+`);
+}
+
+async function run() {
+  const args = process.argv.slice(2);
+
+  // Handle --version anywhere in args
+  if (args.includes('--version') || (args.length === 1 && args[0] === 'version')) {
+    console.log(`stellamail v${version}`);
+    return;
+  }
+
+  if (args.length === 0 || (args.length === 1 && args[0] === '--help')) {
+    showHelp();
+    return;
+  }
+
+  const command = args[0];
+
+  // Handle help
+  if (command === 'help') {
+    showHelp(args[1]);
+    return;
+  }
+
+  // Handle init (no config needed)
+  if (command === 'init') {
+    const init = require('./commands/init');
+    await init.run();
+    return;
+  }
+
+  if (!COMMANDS[command]) {
+    const suggestion = suggestCommand(command);
+    if (suggestion) {
+      console.error(chalk.red(`❌ Unknown command "${command}".`) + ` Did you mean ${chalk.cyan.bold('"' + suggestion + '"')}?`);
+    } else {
+      console.error(chalk.red(`❌ Unknown command: "${command}"`));
+    }
+    console.error(chalk.gray('   Run "stellamail help" for available commands.'));
+    process.exit(1);
+  }
+
+  const opts = parseArgs(args.slice(1));
+
+  // Load config
+  const { config } = findConfig(opts.config);
+
+  // Run command
+  const cmd = require(COMMANDS[command]);
+  await cmd.run(opts, config);
+}
+
+module.exports = { run };

package/src/commands/accounts.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { makeTable, chalk } = require('../format');
+
+async function run(opts, config) {
+  const accounts = config.accounts ? Object.keys(config.accounts) : [];
+  const isJson = opts.output === 'json';
+
+  if (accounts.length === 0) {
+    if (isJson) {
+      console.log(JSON.stringify([]));
+    } else {
+      console.log(chalk.yellow('No accounts configured.'));
+    }
+    return;
+  }
+
+  if (isJson) {
+    const jsonAccounts = accounts.map(name => {
+      const acct = config.accounts[name];
+      const smtpHost = (acct.smtp && acct.smtp.host) || (config.smtp && config.smtp.host) || null;
+      return {
+        name,
+        from: acct.from || null,
+        smtpHost,
+        hasImap: !!acct.imap
+      };
+    });
+    console.log(JSON.stringify(jsonAccounts, null, 2));
+    return;
+  }
+
+  console.log(chalk.cyan('📧 Configured Accounts'));
+
+  const table = makeTable(['Account', 'From', 'SMTP Host', 'IMAP'], [12, 28, 20, 10]);
+
+  for (const name of accounts) {
+    const acct = config.accounts[name];
+    const smtpHost = (acct.smtp && acct.smtp.host) || (config.smtp && config.smtp.host) || '';
+    const hasImap = acct.imap ? chalk.green('✅') : chalk.red('❌');
+
+    table.push([
+      chalk.cyan.bold(name),
+      chalk.green(acct.from || ''),
+      smtpHost,
+      hasImap
+    ]);
+  }
+
+  console.log(table.toString());
+}
+
+const help = `
+stellamail accounts — List configured accounts
+
+USAGE:
+  stellamail accounts [options]
+
+OPTIONS:
+  --output json       Output as JSON
+  --config <path>     Path to config file
+`;
+
+module.exports = { run, help };

package/src/commands/delete.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { getAccount } = require('../config');
+const { withImap } = require('../imap');
+const { chalk } = require('../format');
+
+async function run(opts, config) {
+  const id = opts._positional && opts._positional[0];
+  if (!id) {
+    console.error(chalk.red('❌ Usage: stellamail delete <id> --account <name>'));
+    process.exit(1);
+  }
+  if (!opts.account) {
+    console.error(chalk.red('❌ --account is required for delete'));
+    process.exit(1);
+  }
+
+  const acctConfig = getAccount(config, opts.account);
+  const folder = opts.folder || 'INBOX';
+  const seq = parseInt(id, 10);
+  const permanent = !!opts.permanent;
+  const isJson = opts.output === 'json';
+
+  await withImap(acctConfig, config, async (client) => {
+    const mailbox = await client.getMailboxLock(folder);
+    try {
+      if (permanent) {
+        await client.messageDelete(String(seq));
+        if (isJson) {
+          console.log(JSON.stringify({
+            status: 'deleted',
+            id: seq,
+            folder,
+            permanent: true,
+            account: opts.account
+          }, null, 2));
+        } else {
+          console.log(chalk.green(`✅ Message #${seq} permanently deleted from "${folder}"`));
+        }
+      } else {
+        await client.messageMove(String(seq), 'Trash');
+        if (isJson) {
+          console.log(JSON.stringify({
+            status: 'deleted',
+            id: seq,
+            folder,
+            movedTo: 'Trash',
+            permanent: false,
+            account: opts.account
+          }, null, 2));
+        } else {
+          console.log(chalk.green(`✅ Message #${seq} moved to Trash`));
+        }
+      }
+    } finally {
+      mailbox.release();
+    }
+  });
+}
+
+const help = `
+stellamail delete — Delete a message
+
+USAGE:
+  stellamail delete <id> --account <name> [options]
+
+REQUIRED:
+  <id>                Message sequence number
+  --account <name>    Account name from config
+
+OPTIONAL:
+  --folder <name>     Source folder (default INBOX)
+  --permanent         Permanently delete (don't move to Trash)
+  --output json       Output as JSON
+  --config <path>     Path to config file
+`;
+
+module.exports = { run, help };