emailr-cli 1.5.0 → 1.5.1

package/dist/index.js

@@ -1008,12 +1008,16 @@ Template: ${template.name}`);
   });
   cmd.command("edit <id>").description(`Start a live editing session for a template.
 
-AGENTIC WORKFLOW:
-1. Run: emailr templates edit <id> --file ./template.html
+AGENTIC WORKFLOW (for AI agents, use --background):
+1. Run: emailr templates edit <id> --file ./template.html --background
 2. Edit the file at ./template.html - browser auto-refreshes on save
 3. When done: emailr templates update <id> --html-file ./template.html
+4. Stop server: emailr templates stop-preview
 
-This command fetches the template HTML, saves it locally, and starts a live preview server with hot-reload. Any changes to the file are instantly reflected in the browser.`).option("--file <path>", "Path to save the HTML file for editing", "./template.html").option("--no-open", "Do not automatically open browser").action(async (id, options) => {
+INTERACTIVE MODE (default):
+1. Run: emailr templates edit <id> --file ./template.html
+2. Edit the file - browser auto-refreshes on save
+3. Press Ctrl+C when done, then run update command`).option("--file <path>", "Path to save the HTML file for editing", "./template.html").option("--no-open", "Do not automatically open browser").option("--background", "Start preview server in background and exit (for AI agents)").action(async (id, options) => {
     try {
       const config = loadConfig();
       const client = new Emailr3({
@@ -1026,6 +1030,95 @@ This command fetches the template HTML, saves it locally, and starts a live prev
       const htmlContent = template.html_content ?? "";
       fs4.writeFileSync(filePath, htmlContent, "utf-8");
       console.log(`Template saved to: ${filePath}`);
+      if (options.background) {
+        const { spawn: spawn2 } = await import("child_process");
+        const os4 = await import("os");
+        const pidFile = path4.join(os4.tmpdir(), "emailr-preview.pid");
+        try {
+          const existingPid = fs4.readFileSync(pidFile, "utf-8").trim();
+          process.kill(parseInt(existingPid, 10), "SIGTERM");
+        } catch {
+        }
+        const serverCode = `
+            const http = require('http');
+            const fs = require('fs');
+            const path = require('path');
+            const os = require('os');
+            const filePath = ${JSON.stringify(filePath)};
+            const pidFile = path.join(os.tmpdir(), 'emailr-preview.pid');
+            const portFile = path.join(os.tmpdir(), 'emailr-preview.port');
+            let clients = [];
+            const script = '<script>(function(){const e=new EventSource("/__live-reload");e.onmessage=function(d){if(d.data==="reload")location.reload()};})();</script>';
+            const server = http.createServer((req, res) => {
+              if (req.url === '/__live-reload') {
+                res.writeHead(200, {'Content-Type':'text/event-stream','Cache-Control':'no-cache','Connection':'keep-alive'});
+                res.write('data: connected\\n\\n');
+                clients.push(res);
+                req.on('close', () => { clients = clients.filter(c => c !== res); });
+                return;
+              }
+              try {
+                let html = fs.readFileSync(filePath, 'utf-8');
+                html = html.includes('</body>') ? html.replace('</body>', script + '</body>') : html + script;
+                res.writeHead(200, {'Content-Type':'text/html; charset=utf-8'});
+                res.end(html);
+              } catch (e) {
+                res.writeHead(500);
+                res.end('Error: ' + e.message);
+              }
+            });
+            server.listen(0, '127.0.0.1', () => {
+              const port = server.address().port;
+              fs.writeFileSync(pidFile, String(process.pid));
+              fs.writeFileSync(portFile, String(port));
+              console.log('PORT:' + port);
+              let timer;
+              fs.watch(filePath, () => {
+                clearTimeout(timer);
+                timer = setTimeout(() => clients.forEach(c => { try { c.write('data: reload\\n\\n'); } catch {} }), 100);
+              });
+            });
+            process.on('SIGTERM', () => { try { fs.unlinkSync(pidFile); fs.unlinkSync(portFile); } catch {} process.exit(0); });
+          `;
+        const child = spawn2("node", ["-e", serverCode], {
+          detached: true,
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+        let port2 = "";
+        await new Promise((resolve) => {
+          child.stdout?.on("data", (data) => {
+            const output2 = data.toString();
+            const match = output2.match(/PORT:(\d+)/);
+            if (match) {
+              port2 = match[1];
+              resolve();
+            }
+          });
+          setTimeout(resolve, 3e3);
+        });
+        child.unref();
+        const previewUrl2 = `http://127.0.0.1:${port2}/`;
+        console.log(`
+Template: ${template.name}`);
+        console.log(`Template ID: ${template.id}`);
+        console.log(`Live Preview: ${previewUrl2}`);
+        console.log(`File: ${filePath}`);
+        console.log(`
+Preview server running in background (PID: ${child.pid}).`);
+        console.log(`Edit the file and see live updates in the browser.`);
+        console.log(`
+When done:`);
+        console.log(`  emailr templates update ${id} --html-file ${options.file}`);
+        console.log(`  emailr templates stop-preview`);
+        if (options.open !== false) {
+          try {
+            const open = await import("open");
+            await open.default(previewUrl2);
+          } catch {
+          }
+        }
+        process.exit(0);
+      }
       const port = await startLivePreviewServer(filePath, () => {
         console.log("File changed - browser refreshed");
       });
@@ -1034,6 +1127,7 @@ This command fetches the template HTML, saves it locally, and starts a live prev
 Template: ${template.name}`);
       console.log(`Template ID: ${template.id}`);
       console.log(`Live Preview: ${previewUrl}`);
+      console.log(`File: ${filePath}`);
       console.log(`
 Watching for changes... Edit the file and see live updates.`);
       console.log(`When done, run: emailr templates update ${id} --html-file ${options.file}`);
@@ -1061,12 +1155,16 @@ To save changes: emailr templates update ${id} --html-file ${options.file}`);
   });
   cmd.command("draft").description(`Start a live drafting session for a new template.
 
-AGENTIC WORKFLOW:
-1. Run: emailr templates draft --file ./new-template.html
+AGENTIC WORKFLOW (for AI agents, use --background):
+1. Run: emailr templates draft --file ./new-template.html --background
 2. Edit the file at ./new-template.html - browser auto-refreshes on save
 3. When done: emailr templates create --name "My Template" --subject "Subject" --html-file ./new-template.html
+4. Stop server: emailr templates stop-preview
 
-This command creates a starter HTML file and starts a live preview server with hot-reload. Perfect for building new templates from scratch with instant visual feedback.`).option("--file <path>", "Path to save the HTML file for drafting", "./new-template.html").option("--no-open", "Do not automatically open browser").option("--blank", "Start with a blank file instead of starter template").action(async (options) => {
+INTERACTIVE MODE (default):
+1. Run: emailr templates draft --file ./new-template.html
+2. Edit the file - browser auto-refreshes on save
+3. Press Ctrl+C when done, then run create command`).option("--file <path>", "Path to save the HTML file for drafting", "./new-template.html").option("--no-open", "Do not automatically open browser").option("--blank", "Start with a blank file instead of starter template").option("--background", "Start preview server in background and exit (for AI agents)").action(async (options) => {
     try {
       const filePath = path4.resolve(options.file);
       let htmlContent;
@@ -1088,51 +1186,21 @@ This command creates a starter HTML file and starts a live preview server with h
       margin: 0 auto;
       padding: 20px;
     }
-    .header {
-      text-align: center;
-      padding: 20px 0;
-      border-bottom: 1px solid #eee;
-    }
-    .content {
-      padding: 30px 0;
-    }
-    .button {
-      display: inline-block;
-      padding: 12px 24px;
-      background-color: #5e5de7;
-      color: white;
-      text-decoration: none;
-      border-radius: 5px;
-      font-weight: bold;
-    }
-    .footer {
-      text-align: center;
-      padding: 20px 0;
-      border-top: 1px solid #eee;
-      color: #888;
-      font-size: 12px;
-    }
+    .header { text-align: center; padding: 20px 0; border-bottom: 1px solid #eee; }
+    .content { padding: 30px 0; }
+    .button { display: inline-block; padding: 12px 24px; background-color: #5e5de7; color: white; text-decoration: none; border-radius: 5px; font-weight: bold; }
+    .footer { text-align: center; padding: 20px 0; border-top: 1px solid #eee; color: #888; font-size: 12px; }
   </style>
 </head>
 <body>
-  <div class="header">
-    <h1>Your Company</h1>
-  </div>
-  
+  <div class="header"><h1>Your Company</h1></div>
   <div class="content">
     <h2>Hello {{name}},</h2>
-    
     <p>This is a starter template. Edit this file and see your changes live in the browser!</p>
-    
     <p>You can use variables like <code>{{name}}</code> that will be replaced when sending emails.</p>
-    
-    <p style="text-align: center; margin: 30px 0;">
-      <a href="https://example.com" class="button">Call to Action</a>
-    </p>
-    
+    <p style="text-align: center; margin: 30px 0;"><a href="https://example.com" class="button">Call to Action</a></p>
     <p>Best regards,<br>Your Team</p>
   </div>
-  
   <div class="footer">
     <p>\xA9 2024 Your Company. All rights reserved.</p>
     <p><a href="{{unsubscribe_link}}">Unsubscribe</a></p>
@@ -1142,12 +1210,99 @@ This command creates a starter HTML file and starts a live preview server with h
       }
       fs4.writeFileSync(filePath, htmlContent, "utf-8");
       console.log(`Template draft created: ${filePath}`);
+      if (options.background) {
+        const { spawn: spawn2 } = await import("child_process");
+        const os4 = await import("os");
+        const pidFile = path4.join(os4.tmpdir(), "emailr-preview.pid");
+        try {
+          const existingPid = fs4.readFileSync(pidFile, "utf-8").trim();
+          process.kill(parseInt(existingPid, 10), "SIGTERM");
+        } catch {
+        }
+        const serverCode = `
+            const http = require('http');
+            const fs = require('fs');
+            const path = require('path');
+            const os = require('os');
+            const filePath = ${JSON.stringify(filePath)};
+            const pidFile = path.join(os.tmpdir(), 'emailr-preview.pid');
+            const portFile = path.join(os.tmpdir(), 'emailr-preview.port');
+            let clients = [];
+            const script = '<script>(function(){const e=new EventSource("/__live-reload");e.onmessage=function(d){if(d.data==="reload")location.reload()};})();</script>';
+            const server = http.createServer((req, res) => {
+              if (req.url === '/__live-reload') {
+                res.writeHead(200, {'Content-Type':'text/event-stream','Cache-Control':'no-cache','Connection':'keep-alive'});
+                res.write('data: connected\\n\\n');
+                clients.push(res);
+                req.on('close', () => { clients = clients.filter(c => c !== res); });
+                return;
+              }
+              try {
+                let html = fs.readFileSync(filePath, 'utf-8');
+                html = html.includes('</body>') ? html.replace('</body>', script + '</body>') : html + script;
+                res.writeHead(200, {'Content-Type':'text/html; charset=utf-8'});
+                res.end(html);
+              } catch (e) {
+                res.writeHead(500);
+                res.end('Error: ' + e.message);
+              }
+            });
+            server.listen(0, '127.0.0.1', () => {
+              const port = server.address().port;
+              fs.writeFileSync(pidFile, String(process.pid));
+              fs.writeFileSync(portFile, String(port));
+              console.log('PORT:' + port);
+              let timer;
+              fs.watch(filePath, () => {
+                clearTimeout(timer);
+                timer = setTimeout(() => clients.forEach(c => { try { c.write('data: reload\\n\\n'); } catch {} }), 100);
+              });
+            });
+            process.on('SIGTERM', () => { try { fs.unlinkSync(pidFile); fs.unlinkSync(portFile); } catch {} process.exit(0); });
+          `;
+        const child = spawn2("node", ["-e", serverCode], {
+          detached: true,
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+        let port2 = "";
+        await new Promise((resolve) => {
+          child.stdout?.on("data", (data) => {
+            const match = data.toString().match(/PORT:(\d+)/);
+            if (match) {
+              port2 = match[1];
+              resolve();
+            }
+          });
+          setTimeout(resolve, 3e3);
+        });
+        child.unref();
+        const previewUrl2 = `http://127.0.0.1:${port2}/`;
+        console.log(`
+Live Preview: ${previewUrl2}`);
+        console.log(`File: ${filePath}`);
+        console.log(`
+Preview server running in background (PID: ${child.pid}).`);
+        console.log(`Edit the file and see live updates in the browser.`);
+        console.log(`
+When done:`);
+        console.log(`  emailr templates create --name "Template Name" --subject "Email Subject" --html-file ${options.file}`);
+        console.log(`  emailr templates stop-preview`);
+        if (options.open !== false) {
+          try {
+            const open = await import("open");
+            await open.default(previewUrl2);
+          } catch {
+          }
+        }
+        process.exit(0);
+      }
       const port = await startLivePreviewServer(filePath, () => {
         console.log("File changed - browser refreshed");
       });
       const previewUrl = `http://127.0.0.1:${port}/`;
       console.log(`
 Live Preview: ${previewUrl}`);
+      console.log(`File: ${filePath}`);
       console.log(`
 Watching for changes... Edit the file and see live updates.`);
       console.log(`
@@ -1175,6 +1330,18 @@ To create template: emailr templates create --name "Template Name" --subject "Em
       process.exit(1);
     }
   });
+  cmd.command("stop-preview").description("Stop any running background preview server").action(async () => {
+    const os4 = await import("os");
+    const pidFile = path4.join(os4.tmpdir(), "emailr-preview.pid");
+    try {
+      const pid = fs4.readFileSync(pidFile, "utf-8").trim();
+      process.kill(parseInt(pid, 10), "SIGTERM");
+      fs4.unlinkSync(pidFile);
+      success("Preview server stopped");
+    } catch {
+      success("No preview server running");
+    }
+  });
   return cmd;
 }
 
@@ -2341,15 +2508,19 @@ description: Operate the Emailr CLI to send emails, manage contacts, templates,
 
 ## LIVE TEMPLATE EDITING (Agentic Workflow)
 
+IMPORTANT: Always use \`--background\` flag so the command returns immediately and you can continue editing.
+
 ### Edit existing template with live preview
-1. Start live editing: \`emailr templates edit <template_id> --file ./template.html\`
-2. Edit the file - browser auto-refreshes on every save
+1. Start live editing: \`emailr templates edit <template_id> --file ./template.html --background\`
+2. Edit the file at ./template.html - browser auto-refreshes on every save
 3. When satisfied: \`emailr templates update <template_id> --html-file ./template.html\`
+4. Stop server: \`emailr templates stop-preview\`
 
 ### Create new template with live preview  
-1. Start drafting: \`emailr templates draft --file ./new-template.html\`
-2. Edit the file - browser auto-refreshes on every save
+1. Start drafting: \`emailr templates draft --file ./new-template.html --background\`
+2. Edit the file at ./new-template.html - browser auto-refreshes on every save
 3. When satisfied: \`emailr templates create --name "Template Name" --subject "Subject" --html-file ./new-template.html\`
+4. Stop server: \`emailr templates stop-preview\`
 
 ## Common commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emailr-cli",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Command-line interface for the Emailr email API",
   "type": "module",
   "bin": {