@emailens/cli 0.3.2 → 0.3.4

package/README.md

@@ -1,6 +1,11 @@
 # @emailens/cli
 
-CLI tool for email compatibility analysis — preview how HTML emails render across 12 email clients (Gmail, Outlook, Apple Mail, Yahoo, Samsung, Thunderbird, HEY, Superhuman).
+[![npm](https://img.shields.io/npm/v/@emailens/cli)](https://www.npmjs.com/package/@emailens/cli)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/emailens/mcp)
+
+CLI tool for email compatibility analysis — preview how HTML emails render across 15 email clients (Gmail, Outlook, Apple Mail, Yahoo, Samsung, Thunderbird, HEY, Superhuman).
+
+> **Prefer AI?** Use the [MCP server](https://github.com/emailens/mcp) — same engine, works with Claude, Cursor, and any MCP client.
 
 ## Install
 
@@ -74,9 +79,75 @@ cat email.html | emailens fix - --format jsx       # Pipe from stdin
 | `--estimate` | | Only show token estimate without calling the AI |
 | `--max-tokens` | | Maximum input tokens for the prompt (default: 16000) |
 
+### `emailens lint <file|glob>`
+
+CI/CD-friendly linting with structured exit codes. Flattens all audit checks (compatibility, content hygiene, links, accessibility, images, inbox preview, size, template variables) into a unified issue list.
+
+```bash
+emailens lint email.html
+emailens lint src/*.html
+emailens lint email.html --json
+emailens lint email.html --fail-on-warning
+emailens lint email.html --skip spam,links
+emailens lint email.html --max-warnings 5
+```
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--format` | `-f` | Input format: `html`, `jsx`, `mjml`, `maizzle` |
+| `--json` | | Output as JSON |
+| `--fail-on-warning` | | Exit 2 if warnings found |
+| `--skip` | | Comma-separated checks to skip: `spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables` |
+| `--max-warnings` | | Fail if more than n warnings |
+
+**Exit codes:**
+- `0` — clean
+- `1` — errors found
+- `2` — warnings only (with `--fail-on-warning` or `--max-warnings` exceeded)
+
+**Output format:**
+
+```
+src/emails/welcome.html
+  error  outlook-windows     border-radius           Not supported in Outlook Windows
+  warn   spam                caps-ratio              20%+ of words are ALL CAPS
+
+src/emails/newsletter.html
+  pass   No issues found
+
+2 files | 1 error | 1 warning
+```
+
+#### CI / GitHub Actions
+
+Drop this into `.github/workflows/email-lint.yml` to fail PRs that introduce broken email CSS, spam triggers, or accessibility regressions:
+
+```yaml
+name: Email lint
+
+on:
+  pull_request:
+    paths:
+      - 'emails/**'
+      - 'src/emails/**'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Lint emails
+        run: npx -y @emailens/cli lint 'emails/**/*.{html,tsx,mjml}' --fail-on-warning
+```
+
+For React Email / MJML / Maizzle source files, the CLI auto-detects the format from the extension. Want full preview reports (with screenshots and shareable links) on every PR? Use the [Emailens GitHub Action](https://github.com/marketplace/actions/emailens-email-preview-check) instead — it wraps the same engine.
+
 ### `emailens clients`
 
-List all 12 supported email clients.
+List all 15 supported email clients.
 
 ```bash
 emailens clients

package/dist/chunk-7OCVIDC7.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};
+//# sourceMappingURL=chunk-7OCVIDC7.js.map

package/dist/chunk-7OCVIDC7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import {
+  __require
+} from "./chunk-7OCVIDC7.js";
 
 // src/index.ts
-import { defineCommand as defineCommand7, runMain } from "citty";
+import { defineCommand as defineCommand8, runMain } from "citty";
 
 // src/commands/analyze.ts
 import { defineCommand } from "citty";
@@ -24,7 +27,7 @@ async function readInput(pathOrStdin) {
       return readFileSync("/dev/stdin", "utf-8");
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const chunks = [];
       process.stdin.resume();
       process.stdin.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
@@ -33,7 +36,7 @@ async function readInput(pathOrStdin) {
         if (!data.trim()) {
           reject(new Error("No input received from stdin. Pipe HTML or provide a file path."));
         } else {
-          resolve2(data);
+          resolve3(data);
         }
       });
       process.stdin.on("error", () => {
@@ -394,7 +397,7 @@ var preview_default = defineCommand2({
         const outDir = args.out ?? "./emailens-screenshots";
         spinner?.start("Capturing screenshots...");
         try {
-          const { captureScreenshots } = await import("./screenshots-PMZQU5V7.js");
+          const { captureScreenshots } = await import("./screenshots-UOLRXFAJ.js");
           const results = await captureScreenshots(
             transforms,
             outDir,
@@ -566,6 +569,11 @@ function escapeHtml(str) {
 }
 
 // src/commands/export.ts
+var toPlainText = null;
+try {
+  ({ toPlainText } = __require("@emailens/engine"));
+} catch {
+}
 var export_default = defineCommand4({
   meta: {
     name: "export",
@@ -605,6 +613,10 @@ var export_default = defineCommand4({
       type: "boolean",
       description: "Export as JSON instead of HTML"
     },
+    "plain-text": {
+      type: "boolean",
+      description: "Also export a plain text version (.txt) for multipart emails"
+    },
     quiet: {
       type: "boolean",
       alias: "q",
@@ -650,7 +662,7 @@ var export_default = defineCommand4({
       if (args.screenshots) {
         spinner?.start("Capturing screenshots...");
         try {
-          const { captureScreenshots } = await import("./screenshots-PMZQU5V7.js");
+          const { captureScreenshots } = await import("./screenshots-UOLRXFAJ.js");
           const screenshotDir = join(outDir, "screenshots");
           const results = await captureScreenshots(
             transforms,
@@ -684,6 +696,15 @@ var export_default = defineCommand4({
         writeFileSync(htmlPath, htmlReport);
         spinner?.succeed(`HTML report saved to ${htmlPath}`);
       }
+      if (args["plain-text"] && toPlainText) {
+        spinner?.start("Generating plain text version...");
+        const plainText = toPlainText(html);
+        const txtPath = join(outDir, "email.txt");
+        writeFileSync(txtPath, plainText);
+        spinner?.succeed(`Plain text saved to ${txtPath}`);
+      } else if (args["plain-text"] && !toPlainText) {
+        spinner?.warn("Plain text export requires @emailens/engine >=0.8.6");
+      }
       if (!args.quiet) {
         console.log();
         console.log(`  Output: ${outDir}`);
@@ -840,7 +861,7 @@ var fix_default = defineCommand5({
       spinner?.start("Generating AI fix...");
       let Anthropic;
       try {
-        Anthropic = (await import("./sdk-HQZAL655.js")).default;
+        Anthropic = (await import("./sdk-IYJIYBYM.js")).default;
       } catch {
         spinner?.fail("@anthropic-ai/sdk is required for the fix command");
         console.error(pc3.dim("\n  Install it with: npm install @anthropic-ai/sdk\n"));
@@ -990,7 +1011,7 @@ function printQualitySummary(report, skip, options) {
   if (!skip.includes("spam")) {
     const { score, level, issues } = report.spam;
     const color = score >= 90 ? pc4.green : score >= 70 ? pc4.yellow : pc4.red;
-    table.push(["Spam Score", `${color(String(score))}/100 (${level}) \u2014 ${issues.length} issue${issues.length === 1 ? "" : "s"}`]);
+    table.push(["Content Hygiene", `${color(String(score))}/100 (${level}) \u2014 ${issues.length} issue${issues.length === 1 ? "" : "s"}`]);
   }
   if (!skip.includes("links")) {
     const { totalLinks, issues } = report.links;
@@ -1011,11 +1032,275 @@ function printQualitySummary(report, skip, options) {
   console.log();
 }
 
+// src/commands/lint.ts
+import { defineCommand as defineCommand7 } from "citty";
+import pc5 from "picocolors";
+import { compile as compile6 } from "@emailens/engine/compile";
+import {
+  auditEmail as auditEmail2,
+  CompileError as CompileError6
+} from "@emailens/engine";
+import { readdir } from "fs/promises";
+import { resolve as resolve2, relative } from "path";
+var VALID_SKIPS2 = /* @__PURE__ */ new Set([
+  "spam",
+  "links",
+  "accessibility",
+  "images",
+  "compatibility",
+  "inboxPreview",
+  "size",
+  "templateVariables"
+]);
+var lint_default = defineCommand7({
+  meta: {
+    name: "lint",
+    description: "Lint HTML emails for compatibility, spam, accessibility, and more. CI/CD-friendly with structured exit codes."
+  },
+  args: {
+    input: {
+      type: "positional",
+      description: "HTML file path or glob pattern",
+      required: true
+    },
+    format: {
+      type: "string",
+      alias: "f",
+      description: "Input format: html, jsx, mjml, maizzle"
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON"
+    },
+    failOnWarning: {
+      type: "boolean",
+      description: "Exit 2 if warnings found"
+    },
+    skip: {
+      type: "string",
+      description: "Comma-separated checks to skip: spam,links,accessibility,images,compatibility,inboxPreview,size,templateVariables"
+    },
+    maxWarnings: {
+      type: "string",
+      description: "Fail if more than n warnings"
+    }
+  },
+  async run({ args }) {
+    try {
+      const skip = [];
+      if (args.skip) {
+        for (const s of args.skip.split(",").map((s2) => s2.trim()).filter(Boolean)) {
+          if (!VALID_SKIPS2.has(s)) {
+            throw new Error(`Unknown skip value "${s}". Valid: ${Array.from(VALID_SKIPS2).join(", ")}`);
+          }
+          skip.push(s);
+        }
+      }
+      const maxWarningsRaw = args.maxWarnings !== void 0 ? parseInt(args.maxWarnings, 10) : void 0;
+      if (maxWarningsRaw !== void 0 && isNaN(maxWarningsRaw)) {
+        throw new Error(`--maxWarnings must be a number, got: ${args.maxWarnings}`);
+      }
+      const maxWarnings = maxWarningsRaw ?? Infinity;
+      const files = await resolveGlob(args.input);
+      if (files.length === 0) {
+        if (args.json) {
+          console.log(JSON.stringify({ files: [], totalErrors: 0, totalWarnings: 0 }));
+        } else {
+          console.error(pc5.red(`No files found matching: ${args.input}`));
+        }
+        process.exit(1);
+      }
+      const results = [];
+      let totalErrors = 0;
+      let totalWarnings = 0;
+      for (const file of files) {
+        const format = resolveFormat(args.format, file);
+        const source = await readInput(file);
+        const html = await compile6(source, format, file);
+        const framework = toFramework(format);
+        const report = auditEmail2(html, {
+          framework,
+          skip
+        });
+        const issues = flattenToLintIssues(report, skip);
+        const errors = issues.filter((i) => i.severity === "error").length;
+        const warnings = issues.filter((i) => i.severity === "warning").length;
+        results.push({ file: relative(process.cwd(), file), issues, errors, warnings });
+        totalErrors += errors;
+        totalWarnings += warnings;
+      }
+      if (args.json) {
+        console.log(JSON.stringify({ files: results, totalErrors, totalWarnings }, null, 2));
+      } else {
+        for (const result of results) {
+          console.log(pc5.underline(result.file));
+          if (result.issues.length === 0) {
+            console.log(`  ${pc5.green("pass")}  No issues found`);
+          } else {
+            for (const issue of result.issues) {
+              const sev = issue.severity === "error" ? pc5.red("error") : issue.severity === "warning" ? pc5.yellow("warn ") : pc5.blue("info ");
+              console.log(`  ${sev}  ${pc5.dim(issue.category.padEnd(18))}  ${pc5.bold(issue.rule.padEnd(22))}  ${issue.message}`);
+            }
+          }
+          console.log();
+        }
+        const summary = [
+          `${files.length} file${files.length === 1 ? "" : "s"}`,
+          totalErrors > 0 ? pc5.red(`${totalErrors} error${totalErrors === 1 ? "" : "s"}`) : null,
+          totalWarnings > 0 ? pc5.yellow(`${totalWarnings} warning${totalWarnings === 1 ? "" : "s"}`) : null,
+          totalErrors === 0 && totalWarnings === 0 ? pc5.green("all clean") : null
+        ].filter(Boolean).join(" | ");
+        console.log(summary);
+      }
+      if (totalErrors > 0) {
+        process.exit(1);
+      }
+      if (args.failOnWarning && totalWarnings > 0) {
+        if (!args.json) {
+          console.error(pc5.yellow(`
+Failed: ${totalWarnings} warning${totalWarnings === 1 ? "" : "s"} found (--failOnWarning)`));
+        }
+        process.exit(2);
+      }
+      if (Number.isFinite(maxWarnings) && totalWarnings > maxWarnings) {
+        if (!args.json) {
+          console.error(pc5.red(`
+Exceeded max warnings: ${totalWarnings} > ${maxWarnings}`));
+        }
+        process.exit(2);
+      }
+    } catch (err) {
+      if (err instanceof CompileError6) {
+        console.error(pc5.red(`Compilation failed (${err.phase}): ${err.message}`));
+      } else {
+        console.error(pc5.red(err.message));
+      }
+      process.exit(1);
+    }
+  }
+});
+async function resolveGlob(pattern) {
+  if (!pattern.includes("*")) {
+    return [resolve2(pattern)];
+  }
+  if (pattern.includes("**")) {
+    throw new Error("Recursive glob (**) is not supported. Use a single-level wildcard (e.g., src/*.html) or list files explicitly.");
+  }
+  const lastSep = Math.max(pattern.lastIndexOf("/"), pattern.lastIndexOf("\\"));
+  const dir = lastSep >= 0 ? pattern.slice(0, lastSep) : ".";
+  const glob = lastSep >= 0 ? pattern.slice(lastSep + 1) : pattern;
+  const regex = new RegExp("^" + glob.replace(/\*/g, ".*") + "$");
+  const entries = await readdir(resolve2(dir), { withFileTypes: true });
+  return entries.filter((e) => e.isFile() && regex.test(e.name)).map((e) => resolve2(dir, e.name)).sort();
+}
+function flattenToLintIssues(report, skip) {
+  const issues = [];
+  if (!skip.includes("compatibility")) {
+    const seenProps = /* @__PURE__ */ new Map();
+    for (const w of report.compatibility.warnings) {
+      const key = `${w.property}\0${w.severity}`;
+      const existing = seenProps.get(key);
+      if (existing) {
+        existing.clients.push(w.client);
+      } else {
+        seenProps.set(key, {
+          severity: w.severity,
+          clients: [w.client],
+          message: w.message
+        });
+      }
+    }
+    for (const [key, val] of seenProps) {
+      const property = key.split("\0")[0];
+      issues.push({
+        severity: val.severity,
+        category: val.clients.slice(0, 3).join(",") + (val.clients.length > 3 ? `+${val.clients.length - 3}` : ""),
+        rule: property,
+        message: val.message
+      });
+    }
+  }
+  if (!skip.includes("spam")) {
+    for (const issue of report.spam.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "spam",
+        rule: issue.rule,
+        message: issue.message,
+        detail: issue.detail
+      });
+    }
+  }
+  if (!skip.includes("links")) {
+    for (const issue of report.links.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "links",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  if (!skip.includes("accessibility")) {
+    for (const issue of report.accessibility.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "accessibility",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  if (!skip.includes("images")) {
+    for (const issue of report.images.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "images",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  if (!skip.includes("inboxPreview")) {
+    for (const issue of report.inboxPreview.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "inboxPreview",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  if (!skip.includes("size")) {
+    for (const issue of report.size.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "size",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  if (!skip.includes("templateVariables")) {
+    for (const issue of report.templateVariables.issues) {
+      issues.push({
+        severity: issue.severity,
+        category: "templateVars",
+        rule: issue.rule,
+        message: issue.message
+      });
+    }
+  }
+  const order = { error: 0, warning: 1, info: 2 };
+  issues.sort((a, b) => order[a.severity] - order[b.severity]);
+  return issues;
+}
+
 // src/index.ts
-var main = defineCommand7({
+var main = defineCommand8({
   meta: {
     name: "emailens",
-    version: "0.3.0",
+    version: "0.4.0",
     description: "Email compatibility analysis CLI \u2014 preview how HTML emails render across 12 email clients."
   },
   subCommands: {
@@ -1024,7 +1309,8 @@ var main = defineCommand7({
     clients: clients_default,
     export: export_default,
     fix: fix_default,
-    audit: audit_default
+    audit: audit_default,
+    lint: lint_default
   }
 });
 runMain(main);