@travetto/email-compiler 8.0.0-alpha.9 → 8.0.1

package/README.md

@@ -13,14 +13,14 @@ npm install @travetto/email-compiler
 yarn add @travetto/email-compiler
 ```
 
-This is primarily a set of command line tools for compiling and developing templates.  The inputs are compiled files, generally under the `support/` folder, that represents the necessary input for the email compilation.  [Email Inky Templates](https://github.com/travetto/travetto/tree/main/module/email-inky#readme "Email Inky templating module") shows this pattern by leveraging [JSX](https://en.wikipedia.org/wiki/JSX_(JavaScript)) bindings for the [inky](https://github.com/zurb/inky) framework, allowing for compile-time checked templates.
+This is primarily a set of command line tools for compiling and developing templates. The inputs are compiled files, generally under the `support/` folder, that represents the necessary input for the email compilation. [Email Inky Templates](https://github.com/travetto/travetto/tree/main/module/email-inky#readme "Email Inky templating module") shows this pattern by leveraging [JSX](https://en.wikipedia.org/wiki/JSX_(JavaScript)) bindings for the [inky](https://github.com/zurb/inky) framework, allowing for compile-time checked templates.
 
 ## Asset Management
-The templating process involves loading various assets (html, css, images), and so there is provision for asset management and loading.  The templating config allows for specifying asset paths, with the following paths (in order of precedence):
+The templating process involves loading various assets (html, css, images), and so there is provision for asset management and loading. The templating config allows for specifying asset paths, with the following paths (in order of precedence):
    1. `%ROOT%/resources/email`
    1. `@travetto/email-{engine}/resources/email`
 
-When looking up a resources, every asset folder is consulted, in order, and the first to resolve an asset wins.  This allows for overriding of default templating resources, as needed.  The compilation process will convert `.email.html` files into `.compiled.html`, `.compiled.text` and `.compiled.subject` suffixes to generate the outputs respectively.
+When looking up a resources, every asset folder is consulted, in order, and the first to resolve an asset wins. This allows for overriding of default templating resources, as needed. The compilation process will convert `.email.html` files into `.compiled.html`, `.compiled.text` and `.compiled.subject` suffixes to generate the outputs respectively.
 
 ## Template Extension
 The template extension points are defined at:
@@ -40,10 +40,10 @@ When referencing an image from the `resources` folder in a template, e.g.
 
 **Code: Sample Image Reference**
 ```html
-<img src="/email/logo.png">
+<img src="/email/logo.png" alt="logo" />
 ```
 
-The image will be extracted out and embedded in the email as a multi part message.  This allows for compression and optimization of images as well as externalizing resources that may not be immediately public.  The currently supported set of image types are:
+The image will be extracted out and embedded in the email as a multi part message. This allows for compression and optimization of images as well as externalizing resources that may not be immediately public. The currently supported set of image types are:
    *  jpeg
    *  png
 
@@ -53,18 +53,27 @@ The module provides [Command Line Interface](https://github.com/travetto/travett
 ## CLI Compilation
 The module provides [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") support for email template compilation also. Running
 
-**Terminal: Running template compilation**
+## CLI - email:compile
+
+**Terminal: Help for email:compile**
 ```bash
 $ trv email:compile --help
 
 Usage: email:compile [options]
 
+Description:
+  Compile all email templates into generated runtime artifacts.
+
+  The command discovers templated inputs (for example, `.email.html`) and emits
+  compiled outputs used at runtime (html/text/subject variants). With watch
+  enabled, recompilation runs automatically on matching template changes.
+
 Options:
-  -w, --watch  Compile in watch mode
+  -w, --watch  Recompile templates whenever source templates change.
   --help       display help for command
 ```
 
-Will convert all `.email.html` files into the appropriate `.compiled.html`, `.compiled.text` and `.compiled.subject` files.  These will be used during the running of the application.  By default these files are added to the `.gitignore` as they are generally not intended to be saved but to be generated during the build process.
+Will convert all `.email.html` files into the appropriate `.compiled.html`, `.compiled.text` and `.compiled.subject` files. These will be used during the running of the application. By default these files are added to the `.gitignore` as they are generally not intended to be saved but to be generated during the build process.
 
 ## VSCode Plugin
 In addition to command line tools, the [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=arcsine.travetto-plugin) also supports:

package/__index__.ts

@@ -1,2 +1,2 @@
 export * from './src/compiler.ts';
-export * from './src/util.ts';
+export * from './src/util.ts';

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@travetto/email-compiler",
-  "version": "8.0.0-alpha.9",
-  "type": "module",
+  "version": "8.0.1",
   "description": "Email compiling module",
   "keywords": [
     "email",
@@ -12,8 +11,12 @@
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/email-compiler"
   },
   "files": [
     "__index__.ts",
@@ -21,26 +24,25 @@
     "!resources",
     "support"
   ],
+  "type": "module",
   "main": "__index__.ts",
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/email-compiler"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@travetto/config": "^8.0.0-alpha.8",
-    "@travetto/di": "^8.0.0-alpha.8",
-    "@travetto/email": "^8.0.0-alpha.8",
-    "@travetto/image": "^8.0.0-alpha.8",
-    "@travetto/runtime": "^8.0.0-alpha.8",
-    "@travetto/worker": "^8.0.0-alpha.8",
-    "@types/inline-css": "^3.0.4",
+    "@css-inline/css-inline": "^0.21.2",
+    "@travetto/config": "^8.0.1",
+    "@travetto/di": "^8.0.1",
+    "@travetto/email": "^8.0.1",
+    "@travetto/image": "^8.0.1",
+    "@travetto/runtime": "^8.0.1",
+    "@travetto/worker": "^8.0.1",
     "html-entities": "^2.6.0",
-    "inline-css": "^4.0.3",
     "purgecss": "^8.0.0",
-    "sass": "^1.98.0"
+    "sass": "^1.104.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.13"
+    "@travetto/cli": "^8.0.1"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {
@@ -52,8 +54,5 @@
     "roles": [
       "build"
     ]
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/compiler.ts

@@ -1,9 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { TypedObject, RuntimeIndex, Runtime, ExecUtil } from '@travetto/runtime';
-import { type EmailCompiled, MailUtil, type EmailTemplateImport, type EmailTemplateModule } from '@travetto/email';
+import { type EmailCompiled, type EmailTemplateImport, type EmailTemplateModule, MailUtil } from '@travetto/email';
 import { ManifestFileUtil } from '@travetto/manifest';
+import { ExecUtil, Runtime, RuntimeIndex, TypedObject } from '@travetto/runtime';
 
 import { EmailCompileUtil } from './util.ts';
 
@@ -11,7 +11,6 @@ import { EmailCompileUtil } from './util.ts';
  * Email compilation support
  */
 export class EmailCompiler {
-
   /**
    * Load Template
    */
@@ -25,13 +24,11 @@ export class EmailCompiler {
    * Grab list of all available templates
    */
   static findAllTemplates(moduleName?: string): string[] {
-    return RuntimeIndex
-      .find({
-        module: module => (!moduleName ? module.roles.includes('std') : moduleName === module.name) && module.production,
-        folder: folder => folder === 'support',
-        file: file => EmailCompileUtil.isTemplateFile(file.sourceFile)
-      })
-      .map(file => file.sourceFile);
+    return RuntimeIndex.find({
+      module: module => (!moduleName ? module.roles.includes('std') : moduleName === module.name) && module.production,
+      folder: folder => folder === 'support',
+      file: file => EmailCompileUtil.isTemplateFile(file.sourceFile)
+    }).map(file => file.sourceFile);
   }
 
   /**
@@ -55,14 +52,16 @@ export class EmailCompiler {
    */
   static async writeTemplate(file: string, message: EmailCompiled): Promise<void> {
     const outs = this.getOutputFiles(file);
-    await Promise.all(TypedObject.keys(outs).map(async key => {
-      if (message[key]) {
-        const content = MailUtil.buildBrand(file, message[key], 'trv email:compile');
-        await ManifestFileUtil.bufferedFileWrite(outs[key], content);
-      } else {
-        await fs.rm(outs[key], { force: true }); // Remove file if data not provided
-      }
-    }));
+    await Promise.all(
+      TypedObject.keys(outs).map(async key => {
+        if (message[key]) {
+          const content = MailUtil.buildBrand(file, message[key], 'trv email:compile');
+          await ManifestFileUtil.bufferedFileWrite(outs[key], content);
+        } else {
+          await fs.rm(outs[key], { force: true }); // Remove file if data not provided
+        }
+      })
+    );
   }
 
   /**
@@ -90,7 +89,7 @@ export class EmailCompiler {
   static async spawnCompile(file: string): Promise<boolean> {
     const child = ExecUtil.spawnPackageCommand('trv', ['email:compile', file], {
       cwd: Runtime.mainSourcePath,
-      env: { ...process.env },
+      env: { ...process.env }
     });
 
     const result = await ExecUtil.getResult(child, { catch: true });
@@ -102,4 +101,4 @@ export class EmailCompiler {
     }
     return result.valid;
   }
-}
+}

package/src/util.ts

@@ -1,9 +1,10 @@
 import path from 'node:path';
+
 import type { CompileResult, Options } from 'sass';
 
 import type { EmailCompiled, EmailTemplateModule, EmailTemplateResource } from '@travetto/email';
 import { ImageUtil } from '@travetto/image';
-import { BinaryUtil, CodecUtil, RuntimeIndex, type BinaryArray } from '@travetto/runtime';
+import { type BinaryArray, BinaryUtil, CodecUtil, RuntimeIndex } from '@travetto/runtime';
 
 type Tokenized = {
   text: string;
@@ -24,7 +25,6 @@ const EXT = /[.]email[.]tsx$/;
  * Email compile tools
  */
 export class EmailCompileUtil {
-
   /**
    * Is file a template?
    */
@@ -47,7 +47,7 @@ export class EmailCompileUtil {
     return {
       html: this.buildOutputPath(file, '.compiled.html', prefix),
       subject: this.buildOutputPath(file, '.compiled.subject', prefix),
-      text: this.buildOutputPath(file, '.compiled.text', prefix),
+      text: this.buildOutputPath(file, '.compiled.text', prefix)
     };
   }
 
@@ -62,11 +62,12 @@ export class EmailCompileUtil {
     let id = 0;
     const tokens = new Map();
     for (const pattern of patterns) {
-      for (const { [0]: all, groups: { prefix, source } = { prefix: '', source: '' } } of text.matchAll(pattern)) {
-        if (source.includes('://')) { // No urls
+      for (const { 0: all, groups: { prefix, source } = { prefix: '', source: '' } } of text.matchAll(pattern)) {
+        if (source.includes('://')) {
+          // No urls
           continue;
         }
-        const token = `@@${id += 1}@@`;
+        const token = `@@${(id += 1)}@@`;
         tokens.set(token, source);
         text = text.replace(all, `${prefix}${token}`);
       }
@@ -85,7 +86,7 @@ export class EmailCompileUtil {
     const compilerOptions: Options<'async'> = {
       sourceMap: false,
       quietDeps: true,
-      loadPaths: options.loader.searchPaths.slice(0),
+      loadPaths: options.loader.searchPaths.slice(0)
     };
 
     let result: CompileResult;
@@ -105,7 +106,7 @@ export class EmailCompileUtil {
     const purge = new PurgeCSS();
     const [result] = await purge.purge({
       content: [{ raw: html, extension: 'html' }],
-      css: [{ raw: css }],
+      css: [{ raw: css }]
     });
     return result.css;
   }
@@ -115,17 +116,14 @@ export class EmailCompileUtil {
    */
   static async inlineCss(html: string, css: string): Promise<string> {
     // Inline css
-    const { default: inlineCss } = await import('inline-css');
-    return inlineCss(
-      // Style needs to be in head to preserve media queries
-      html.replace('</head>', `<style>${css}</style></head>`),
-      {
-        url: 'https://app.dev',
-        preserveMediaQueries: true,
-        removeStyleTags: true,
-        removeLinkTags: true,
-        applyStyleTags: true,
-      });
+    const { inline } = await import('@css-inline/css-inline');
+    return inline(html, {
+      extraCss: css,
+      keepAtRules: true,
+      keepStyleTags: false,
+      keepLinkTags: false,
+      loadRemoteStylesheets: false
+    });
   }
 
   /**
@@ -166,15 +164,17 @@ export class EmailCompileUtil {
    */
   static handleHtmlEdgeCases(html: string): string {
     return html
-      .replace(/\n{3,100}/msg, '\n\n')
+      .replace(/\n{3,100}/gms, '\n\n')
       .replace(/<(meta|img|link|hr|br)[^>]{0,200}>/g, a => a.replace(/>/g, '/>')) // Fix self closing
       .replace(/&apos;/g, '&#39;') // Fix apostrophes, as outlook hates them
-      .replace(/(background(?:-color)?:\s*)([#0-9a-f]{6,8})([^>.#,]+)>/ig,
-        (all, property, color, rest) => `${property}${color}${rest} bgcolor="${color}">`) // Inline bg-color
-      .replace(/<([^>]+vertical-align:\s*(top|bottom|middle)[^>]+)>/g,
-        (a, tag, valign) => tag.indexOf('valign') ? `<${tag}>` : `<${tag} valign="${valign}">`) // Vertically align if it has the style
-      .replace(/<(table[^>]+expand[^>]+width:\s*)(100%\s+!important)([^>]+)>/g,
-        (a, left, size, right) => `<${left}100%${right}>`) // Drop important as a fix for outlook
+      .replace(
+        /(background(?:-color)?:\s*)([#0-9a-f]{6,8})([^>.#,]+)>/gi,
+        (all, property, color, rest) => `${property}${color}${rest} bgcolor="${color}">`
+      ) // Inline bg-color
+      .replace(/<([^>]+vertical-align:\s*(top|bottom|middle)[^>]+)>/g, (a, tag, valign) =>
+        tag.indexOf('valign') ? `<${tag}>` : `<${tag} valign="${valign}">`
+      ) // Vertically align if it has the style
+      .replace(/<(table[^>]+expand[^>]+width:\s*)(100%\s+!important)([^>]+)>/g, (a, left, size, right) => `<${left}100%${right}>`) // Drop important as a fix for outlook
       .trim()
       .concat('\n');
   }
@@ -183,10 +183,7 @@ export class EmailCompileUtil {
    * Apply styles into a given html document
    */
   static async applyStyles(html: string, options: EmailTemplateResource): Promise<string> {
-    const styles = [
-      options.globalStyles ?? '',
-      await options.loader.readUTF8('/email/main.scss').catch(() => '')
-    ]
+    const styles = [options.globalStyles ?? '', await options.loader.readUTF8('/email/main.scss').catch(() => '')]
       .filter(line => !!line)
       .join('\n');
 
@@ -222,4 +219,4 @@ export class EmailCompileUtil {
 
     return { html, subject, text };
   }
-}
+}

package/support/bin/config.ts

@@ -1,8 +1,9 @@
 import fs from 'node:fs/promises';
+
 import { parse, stringify } from 'yaml';
 
-import { Runtime } from '@travetto/runtime';
 import { ManifestFileUtil } from '@travetto/manifest';
+import { Runtime } from '@travetto/runtime';
 
 import type { EditorConfigType } from './types.ts';
 
@@ -12,7 +13,6 @@ export const CONFIG_FILE = 'resources/email/local.yml';
  * Configuration utils
  */
 export class EditorConfig {
-
   static DEFAULT_CONFIG = {
     to: 'my-email@gmail.com',
     from: 'from-email@gmail.com',
@@ -25,8 +25,8 @@ export class EditorConfig {
       auth: {
         user: 'email@blah.com',
         pass: 'password'
-      },
-    },
+      }
+    }
   };
 
   /**
@@ -56,4 +56,4 @@ export class EditorConfig {
     }
     return resolved;
   }
-}
+}

package/support/bin/editor.ts

@@ -1,20 +1,18 @@
 import { Inject, Injectable } from '@travetto/di';
-import { MailUtil, type EmailCompiled, type MailInterpolator } from '@travetto/email';
+import { type EmailCompiled, type MailInterpolator, MailUtil } from '@travetto/email';
 import { RuntimeError, TypedObject, WatchUtil } from '@travetto/runtime';
 
-import type { EditorSendService } from './send.ts';
-import { EditorConfig } from './config.ts';
-import type { EditorRequest, EditorResponse } from './types.ts';
-
 import { EmailCompiler } from '../../src/compiler.ts';
 import { EmailCompileUtil } from '../../src/util.ts';
+import { EditorConfig } from './config.ts';
+import type { EditorSendService } from './send.ts';
+import type { EditorRequest, EditorResponse } from './types.ts';
 
 /**
  * Utils for interacting with editors
  */
 @Injectable()
 export class EditorService {
-
   @Inject()
   sender: EditorSendService;
 
@@ -28,12 +26,11 @@ export class EditorService {
   async #renderTemplate(templateFile: string, context: Record<string, unknown>): Promise<EmailCompiled> {
     const email = await EmailCompiler.compile(templateFile);
     return TypedObject.fromEntries(
-      await Promise.all(TypedObject.entries(email).map(([key, value]) =>
-        this.#interpolate(value, context).then((result) => [key, result])))
+      await Promise.all(TypedObject.entries(email).map(([key, value]) => this.#interpolate(value, context).then(result => [key, result])))
     );
   }
 
-  async #renderFile(file: string): Promise<{ content: EmailCompiled, file: string }> {
+  async #renderFile(file: string): Promise<{ content: EmailCompiled; file: string }> {
     const content = await this.#renderTemplate(file, await EditorConfig.get('context'));
     return { content, file };
   }
@@ -41,7 +38,9 @@ export class EditorService {
   async #response<T>(operation: Promise<T>, success: (value: T) => EditorResponse, fail?: (error: Error) => EditorResponse): Promise<void> {
     try {
       const response = await operation;
-      if (process.connected) { process.send?.(success(response)); }
+      if (process.connected) {
+        process.send?.(success(response));
+      }
     } catch (error) {
       if (fail && process.connected && error && error instanceof Error) {
         process.send?.(fail(error));
@@ -51,11 +50,11 @@ export class EditorService {
     }
   }
 
-  async sendFile(file: string, to?: string): Promise<{ to: string, file: string, url?: string | false | undefined }> {
+  async sendFile(file: string, to?: string): Promise<{ to: string; file: string; url?: string | false | undefined }> {
     const config = await EditorConfig.get();
     to ||= config.to;
     const content = await this.#renderTemplate(file, config.context ?? {});
-    return { to, file, ...await this.sender.send({ from: config.from, to, ...content, }) };
+    return { to, file, ...(await this.sender.send({ from: config.from, to, ...content })) };
   }
 
   /**
@@ -71,7 +70,8 @@ export class EditorService {
           return await this.#response(EditorConfig.ensureConfig(), file => ({ type: 'configured', file }));
         }
         case 'compile': {
-          return await this.#response(this.#renderFile(request.file),
+          return await this.#response(
+            this.#renderFile(request.file),
             result => ({ type: 'compiled', ...result }),
             error => ({ type: 'compiled-failed', message: error.message, stack: error.stack, file: request.file })
           );
@@ -88,13 +88,19 @@ export class EditorService {
 
     process.send({ type: 'init' });
 
-    await WatchUtil.watchCompilerEvents('change',
-      ({ file }) => EmailCompiler.spawnCompile(file).then(success =>
-        success ? this.#response(this.#renderFile(file),
-          result => ({ type: 'compiled', ...result }),
-          error => ({ type: 'compiled-failed', message: error.message, stack: error.stack, file })
-        ) : undefined
-      ),
-      ({ file }) => EmailCompileUtil.isTemplateFile(file));
+    await WatchUtil.watchCompilerEvents(
+      'change',
+      ({ file }) =>
+        EmailCompiler.spawnCompile(file).then(success =>
+          success
+            ? this.#response(
+                this.#renderFile(file),
+                result => ({ type: 'compiled', ...result }),
+                error => ({ type: 'compiled-failed', message: error.message, stack: error.stack, file })
+              )
+            : undefined
+        ),
+      ({ file }) => EmailCompileUtil.isTemplateFile(file)
+    );
   }
-}
+}

package/support/bin/send.ts

@@ -1,7 +1,7 @@
-import { MailService, type EmailOptions, type MailTransport } from '@travetto/email';
 import { DependencyRegistryIndex, Injectable } from '@travetto/di';
-import { toConcrete } from '@travetto/runtime';
+import { type EmailOptions, MailService, type MailTransport } from '@travetto/email';
 import { Registry } from '@travetto/registry';
+import { toConcrete } from '@travetto/runtime';
 
 import { EditorConfig } from './config.ts';
 
@@ -10,7 +10,6 @@ import { EditorConfig } from './config.ts';
  */
 @Injectable()
 export class EditorSendService {
-
   ethereal = false;
 
   async service(): Promise<MailService> {
@@ -22,14 +21,14 @@ export class EditorSendService {
       try {
         const { NodemailerTransport } = await import('@travetto/email-nodemailer');
         const senderConfig = await EditorConfig.get('sender');
-        const cls = class { };
+        const cls = class {};
         DependencyRegistryIndex.getForRegister(cls).register({
           candidates: {
             factory: {
               candidateType: MailTransportTarget,
               factory: () => new NodemailerTransport(senderConfig),
               class: cls,
-              method: 'factory',
+              method: 'factory'
             }
           }
         });
@@ -37,8 +36,12 @@ export class EditorSendService {
 
         this.ethereal = !!senderConfig.host?.includes('ethereal.email');
       } catch {
-        console.error('A mail transport is currently needed to support sending emails.  Please install @travetto/email-nodemailer or any other compatible transport');
-        throw new Error('A mail transport is currently needed to support sending emails.  Please install @travetto/email-nodemailer or any other compatible transport');
+        console.error(
+          'A mail transport is currently needed to support sending emails.  Please install @travetto/email-nodemailer or any other compatible transport'
+        );
+        throw new Error(
+          'A mail transport is currently needed to support sending emails.  Please install @travetto/email-nodemailer or any other compatible transport'
+        );
       }
     }
     const service = await DependencyRegistryIndex.getInstance(MailService);
@@ -72,4 +75,4 @@ export class EditorSendService {
       throw error;
     }
   }
-}
+}

package/support/bin/types.ts

@@ -1,15 +1,15 @@
 export type EditorRequest =
-  { type: 'configure', file: string } |
-  { type: 'compile', file: string } |
-  { type: 'send', file: string, from?: string, to?: string };
+  | { type: 'configure'; file: string }
+  | { type: 'compile'; file: string }
+  | { type: 'send'; file: string; from?: string; to?: string };
 
 export type EditorResponse =
-  { type: 'configured', file: string } |
-  { type: 'sent', to: string, file: string, url?: string | false } |
-  { type: 'compiled', file: string, content: Record<'html' | 'subject' | 'text', string> } |
-  { type: 'sent-failed', message: string, stack: Error['stack'], to: string, file: string } |
-  { type: 'compiled-failed', message: string, stack: Error['stack'], file: string } |
-  { type: 'init' };
+  | { type: 'configured'; file: string }
+  | { type: 'sent'; to: string; file: string; url?: string | false }
+  | { type: 'compiled'; file: string; content: Record<'html' | 'subject' | 'text', string> }
+  | { type: 'sent-failed'; message: string; stack: Error['stack']; to: string; file: string }
+  | { type: 'compiled-failed'; message: string; stack: Error['stack']; file: string }
+  | { type: 'init' };
 
 export type EditorSender = {
   port?: number;

package/support/cli.email_compile.ts

@@ -1,17 +1,20 @@
+import { CliCommand, type CliCommandShape, cliTpl } from '@travetto/cli';
 import { Registry } from '@travetto/registry';
-import { type CliCommandShape, CliCommand, cliTpl } from '@travetto/cli';
 import { Env, Runtime, WatchUtil } from '@travetto/runtime';
 
 import { EmailCompiler } from '../src/compiler.ts';
 import { EmailCompileUtil } from '../src/util.ts';
 
 /**
- * CLI Entry point for running the email server
+ * Compile all email templates into generated runtime artifacts.
+ *
+ * The command discovers templated inputs (for example, `.email.html`) and emits
+ * compiled outputs used at runtime (html/text/subject variants). With watch
+ * enabled, recompilation runs automatically on matching template changes.
  */
 @CliCommand()
 export class EmailCompileCommand implements CliCommandShape {
-
-  /** Compile in watch mode */
+  /** Recompile templates whenever source templates change. */
   watch?: boolean;
 
   finalize(): void {
@@ -30,9 +33,11 @@ export class EmailCompileCommand implements CliCommandShape {
     }
 
     if (this.watch) {
-      await WatchUtil.watchCompilerEvents('change',
+      await WatchUtil.watchCompilerEvents(
+        'change',
         ({ file }) => EmailCompiler.spawnCompile(file),
-        ({ file }) => EmailCompileUtil.isTemplateFile(file));
+        ({ file }) => EmailCompileUtil.isTemplateFile(file)
+      );
     }
   }
-}
+}

package/support/cli.email_editor.ts

@@ -1,14 +1,18 @@
-import { Env } from '@travetto/runtime';
 import { CliCommand, CliProfilesFlag } from '@travetto/cli';
-import { Registry } from '@travetto/registry';
 import { DependencyRegistryIndex } from '@travetto/di';
+import { Registry } from '@travetto/registry';
+import { Env } from '@travetto/runtime';
 
 import { EditorService } from './bin/editor.ts';
 
-/** The email editor compilation service and output serving */
+/**
+ * Start the email template editor service for interactive preview and testing.
+ *
+ * The editor compiles templates on demand and hosts the preview/test workflow
+ * used during local template authoring.
+ */
 @CliCommand()
 export class EmailEditorCommand {
-
   @CliProfilesFlag()
   profile: string[];
 
@@ -21,4 +25,4 @@ export class EmailEditorCommand {
     const service = await DependencyRegistryIndex.getInstance(EditorService);
     await service.listen();
   }
-}
+}

package/support/cli.email_test.ts

@@ -1,18 +1,20 @@
 import path from 'node:path';
 
-import { Registry } from '@travetto/registry';
-import { type CliCommandShape, CliCommand, CliProfilesFlag } from '@travetto/cli';
+import { CliCommand, type CliCommandShape, CliProfilesFlag } from '@travetto/cli';
 import { DependencyRegistryIndex } from '@travetto/di';
+import { Registry } from '@travetto/registry';
 import { Env } from '@travetto/runtime';
 
 import { EditorService } from './bin/editor.ts';
 
 /**
- * CLI Entry point for running the email server
+ * Render and send a template file to a target recipient for quick validation.
+ *
+ * This command is useful during template development to verify real delivery and
+ * formatting without running the full editor workflow.
  */
 @CliCommand()
 export class EmailTestCommand implements CliCommandShape {
-
   @CliProfilesFlag()
   profile: string[];
 
@@ -26,4 +28,4 @@ export class EmailTestCommand implements CliCommandShape {
     const editor = await DependencyRegistryIndex.getInstance(EditorService);
     await editor.sendFile(file, to);
   }
-}
+}