cursorbyemail 0.5.0

package/README.md

@@ -0,0 +1,176 @@
+# cursorbyemail
+
+Email-based conversations with Cursor agents. Get notified via email when your Cursor agent finishes, and reply to continue the conversation.
+
+## How it works
+
+1. **Cursor hook** - When the Cursor agent finishes a task, a hook sends you an email with the agent's response
+2. **Reply via email** - Reply to the email with your follow-up prompt
+3. **Webhook receives reply** - Resend forwards your reply to a local webhook server exposed via ngrok
+4. **Agent resumes** - The webhook triggers `cursor agent --resume` to continue the conversation
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Cursor    │────▶│   Resend    │────▶│    Email    │
+│   Agent     │     │   (send)    │     │    Inbox    │
+└─────────────┘     └─────────────┘     └─────────────┘
+       ▲                                       │
+       │                                       │ reply
+       │                                       ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   cursor    │◀────│   Webhook   │◀────│   Resend    │
+│   --resume  │     │   + ngrok   │     │  (receive)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
+
+## Requirements
+
+- Node.js 18+
+- [Cursor CLI](https://cursor.com/es/docs/cli/installation) installed
+- [Resend](https://resend.com) account with:
+  - API key
+  - Verified domain for sending
+  - Inbound email domain configured
+- [ngrok](https://ngrok.com) account (free tier works)
+
+## Installation
+
+```bash
+npm install cursorbyemail
+```
+
+## Setup
+
+Run the interactive setup wizard:
+
+```bash
+npx cursorbyemail init
+```
+
+The wizard will:
+
+1. Ask you to select your email provider (Resend)
+2. Ask you to select your tunnel provider (ngrok)
+3. Prompt for configuration values:
+   - `CURSOR_EMAIL_TO` - Your email address for notifications
+   - `CURSOR_EMAIL_SUBJECT` - Subject line prefix
+   - `RESEND_API_KEY` - Your Resend API key
+   - `RESEND_FROM` - Sender email address
+   - `RESEND_REPLY_TO` - Reply-to address (your Resend inbound domain)
+   - `NGROK_AUTHTOKEN` - ngrok auth token (optional if globally configured)
+4. Create configuration files:
+   - `.env` with your settings
+   - `.cursor/hooks.json` for Cursor hooks
+   - `.cursor/hooks/` with hook scripts
+5. Install required dependencies
+6. Verify Cursor CLI is installed
+
+## Usage
+
+### Start the webhook server
+
+```bash
+npx cursorbyemail start
+```
+
+This will:
+- Start an Express server on port 8787 (configurable)
+- Create an ngrok tunnel
+- Display the webhook URL to configure in Resend
+
+### Configure Resend webhook
+
+1. Go to [Resend Dashboard](https://resend.com/webhooks)
+2. Add a new webhook endpoint
+3. Use the URL displayed by `cursorbyemail start`:
+   ```
+   https://<your-ngrok-url>/inbound/resend
+   ```
+4. Select the `email.received` event
+
+### Use with Cursor
+
+Just use Cursor as normal. When the agent finishes a task:
+
+1. You'll receive an email with the agent's response
+2. Reply to the email with your follow-up
+3. The agent will resume and process your reply
+4. You'll receive another email with the new response
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `CURSOR_EMAIL_ON_FINISH` | Enable email notifications (`1` to enable) | Yes |
+| `CURSOR_EMAIL_TO` | Email recipient | Yes |
+| `CURSOR_EMAIL_SUBJECT` | Subject line prefix | No |
+| `RESEND_API_KEY` | Resend API key | Yes |
+| `RESEND_FROM` | Sender email | Yes |
+| `RESEND_REPLY_TO` | Reply-to address | Yes |
+| `NGROK_AUTHTOKEN` | ngrok authentication token | No |
+| `WEBHOOK_PORT` | Port for webhook server (default: 8787) | No |
+| `DEFAULT_REPO_PATH` | Default repository path for agent | No |
+| `DRY_RUN` | Test mode without executing agent | No |
+| `CURSOR_DRY_RUN` | Test email hook without sending | No |
+| `CURSOR_HOOK_DEBUG` | Enable debug logging | No |
+
+### Customizing the hooks
+
+The hook scripts are installed to `.cursor/hooks/`:
+
+- `email-on-stop.mjs` - Sends email when agent finishes
+- `webhook.mjs` - Receives inbound emails and resumes agent
+- `beautify-transcript-email-html.js` - Formats emails
+
+You can modify these files to customize behavior.
+
+## CLI Commands
+
+```bash
+# Initialize in a project
+npx cursorbyemail init
+
+# Start webhook server with ngrok
+npx cursorbyemail start
+
+# Start on custom port
+npx cursorbyemail start --port 3000
+```
+
+## Troubleshooting
+
+### Cursor CLI not found
+
+Install the Cursor CLI:
+https://cursor.com/es/docs/cli/installation
+
+### ngrok authentication error
+
+Set your ngrok auth token:
+```bash
+# Add to .env
+NGROK_AUTHTOKEN=your_token_here
+
+# Or configure globally
+ngrok config add-authtoken your_token_here
+```
+
+### Emails not sending
+
+Check your Resend configuration:
+- Verify your domain is properly configured
+- Ensure the `RESEND_FROM` address uses your verified domain
+- Check the `.cursor/hooks/hook.log` file for errors
+
+### Webhook not receiving emails
+
+Ensure:
+- The ngrok tunnel is running (`npx cursorbyemail start`)
+- The webhook URL is correctly configured in Resend
+- The `email.received` event is selected in Resend
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+
+const program = new Command();
+
+program
+  .name("cursorbyemail")
+  .description("Email-based conversations with Cursor agents")
+  .version(pkg.version);
+
+program
+  .command("init")
+  .description("Initialize cursorbyemail in your project")
+  .action(async () => {
+    const { init } = await import("../lib/init.js");
+    await init();
+  });
+
+program
+  .command("start")
+  .description("Start the webhook server with ngrok tunnel")
+  .option("-p, --port <port>", "Port for the webhook server", "8787")
+  .action(async (options) => {
+    const { start } = await import("../lib/start.js");
+    await start({ port: parseInt(options.port, 10) });
+  });
+
+program.parse();

package/lib/check-cursor.js

@@ -0,0 +1,22 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import chalk from "chalk";
+
+const execFileAsync = promisify(execFile);
+
+export async function checkCursorCli() {
+  try {
+    const { stdout } = await execFileAsync("cursor", ["agent", "--version"], {
+      timeout: 10000,
+    });
+    const version = stdout.trim();
+    console.log(chalk.green(`✓ Cursor CLI found: ${version}`));
+    return true;
+  } catch (error) {
+    console.log(chalk.yellow("⚠ Cursor CLI not found or not working"));
+    console.log(chalk.dim("  The Cursor CLI is required for email reply functionality."));
+    console.log(chalk.dim("  Install it from: https://cursor.com/es/docs/cli/installation"));
+    console.log();
+    return false;
+  }
+}

package/lib/index.js

@@ -0,0 +1,3 @@
+export { init } from "./init.js";
+export { start } from "./start.js";
+export { checkCursorCli } from "./check-cursor.js";

package/lib/init.js

@@ -0,0 +1,221 @@
+import prompts from "prompts";
+import chalk from "chalk";
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkCursorCli } from "./check-cursor.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatesDir = join(__dirname, "..", "templates");
+
+export async function init() {
+  console.log();
+  console.log(chalk.bold("cursorbyemail") + " - Email-based conversations with Cursor agents");
+  console.log(chalk.dim("─".repeat(60)));
+  console.log();
+
+  // Service selection
+  const serviceAnswers = await prompts([
+    {
+      type: "select",
+      name: "emailProvider",
+      message: "Select email provider:",
+      choices: [
+        { title: "Resend", value: "resend", description: "Transactional email API" },
+      ],
+      initial: 0,
+    },
+    {
+      type: "select",
+      name: "tunnelProvider",
+      message: "Select tunnel provider:",
+      choices: [
+        { title: "ngrok", value: "ngrok", description: "Secure tunnels to localhost" },
+      ],
+      initial: 0,
+    },
+  ]);
+
+  if (!serviceAnswers.emailProvider || !serviceAnswers.tunnelProvider) {
+    console.log(chalk.red("Setup cancelled."));
+    process.exit(1);
+  }
+
+  console.log();
+  console.log(chalk.bold("Environment Configuration"));
+  console.log(chalk.dim("These values will be stored in your .env file"));
+  console.log();
+
+  // Environment variables prompts
+  const envAnswers = await prompts([
+    {
+      type: "text",
+      name: "CURSOR_EMAIL_TO",
+      message: "Email address to receive notifications:",
+      validate: (v) => v.includes("@") || "Please enter a valid email address",
+    },
+    {
+      type: "text",
+      name: "CURSOR_EMAIL_SUBJECT",
+      message: "Email subject prefix:",
+      initial: "Cursor agent finished",
+    },
+    {
+      type: "password",
+      name: "RESEND_API_KEY",
+      message: "Resend API key (starts with re_):",
+      validate: (v) => v.startsWith("re_") || "Resend API keys start with 're_'",
+    },
+    {
+      type: "text",
+      name: "RESEND_FROM",
+      message: 'Sender email (e.g., "Agent <agent@domain.com>"):',
+      validate: (v) => v.includes("@") || "Please enter a valid sender email",
+    },
+    {
+      type: "text",
+      name: "RESEND_REPLY_TO",
+      message: 'Reply-to address for webhook (e.g., "domain@yoursubdomain.resend.app"):',
+      validate: (v) => v.includes("@") || "Please enter a valid reply-to address",
+    },
+    {
+      type: "text",
+      name: "NGROK_AUTHTOKEN",
+      message: "ngrok auth token (leave empty if globally configured):",
+    },
+  ]);
+
+  if (!envAnswers.CURSOR_EMAIL_TO || !envAnswers.RESEND_API_KEY) {
+    console.log(chalk.red("Setup cancelled."));
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+
+  console.log();
+  console.log(chalk.bold("Setting up files..."));
+  console.log();
+
+  // Create .cursor/hooks directory
+  const cursorHooksDir = join(cwd, ".cursor", "hooks");
+  mkdirSync(cursorHooksDir, { recursive: true });
+  console.log(chalk.green("✓") + ` Created ${chalk.dim(".cursor/hooks/")}`);
+
+  // Copy hooks.json to .cursor/hooks.json
+  const hooksJsonSrc = join(templatesDir, "hooks.json");
+  const hooksJsonDest = join(cwd, ".cursor", "hooks.json");
+  copyFileSync(hooksJsonSrc, hooksJsonDest);
+  console.log(chalk.green("✓") + ` Created ${chalk.dim(".cursor/hooks.json")}`);
+
+  // Copy hook scripts
+  const hookFiles = [
+    "email-on-stop.mjs",
+    "beautify-transcript-email-html.js",
+  ];
+  for (const file of hookFiles) {
+    copyFileSync(join(templatesDir, file), join(cursorHooksDir, file));
+    console.log(chalk.green("✓") + ` Created ${chalk.dim(`.cursor/hooks/${file}`)}`);
+  }
+
+  // Copy webhook server
+  const webhookDest = join(cursorHooksDir, "webhook.mjs");
+  copyFileSync(join(templatesDir, "webhook.mjs"), webhookDest);
+  console.log(chalk.green("✓") + ` Created ${chalk.dim(".cursor/hooks/webhook.mjs")}`);
+
+  // Generate .env file
+  const envContent = `# cursorbyemail configuration
+# Generated by npx cursorbyemail init
+
+# Enable email notifications on agent finish
+CURSOR_EMAIL_ON_FINISH=1
+
+# Email recipient
+CURSOR_EMAIL_TO="${envAnswers.CURSOR_EMAIL_TO}"
+
+# Email subject prefix
+CURSOR_EMAIL_SUBJECT="${envAnswers.CURSOR_EMAIL_SUBJECT}"
+
+# Resend configuration
+RESEND_API_KEY="${envAnswers.RESEND_API_KEY}"
+RESEND_FROM="${envAnswers.RESEND_FROM}"
+RESEND_REPLY_TO="${envAnswers.RESEND_REPLY_TO}"
+
+# ngrok configuration (optional if globally configured)
+${envAnswers.NGROK_AUTHTOKEN ? `NGROK_AUTHTOKEN="${envAnswers.NGROK_AUTHTOKEN}"` : "# NGROK_AUTHTOKEN="}
+
+# Webhook server port
+WEBHOOK_PORT=8787
+
+# Default repository path for webhook (defaults to cwd)
+DEFAULT_REPO_PATH="${cwd}"
+`;
+
+  const envPath = join(cwd, ".env");
+  const envExists = existsSync(envPath);
+  
+  if (envExists) {
+    const existingEnv = readFileSync(envPath, "utf8");
+    writeFileSync(envPath, existingEnv + "\n" + envContent);
+    console.log(chalk.green("✓") + ` Appended to ${chalk.dim(".env")}`);
+  } else {
+    writeFileSync(envPath, envContent);
+    console.log(chalk.green("✓") + ` Created ${chalk.dim(".env")}`);
+  }
+
+  // Add script to package.json if it exists
+  const pkgPath = join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      pkg.scripts = pkg.scripts || {};
+      pkg.scripts["cursor:email-hook"] = "node .cursor/hooks/email-on-stop.mjs";
+      pkg.scripts["cursor:webhook"] = "node .cursor/hooks/webhook.mjs";
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      console.log(chalk.green("✓") + ` Added scripts to ${chalk.dim("package.json")}`);
+    } catch (e) {
+      console.log(chalk.yellow("⚠") + ` Could not update package.json: ${e.message}`);
+    }
+  }
+
+  console.log();
+  console.log(chalk.bold("Installing dependencies..."));
+  console.log();
+
+  // Install required dependencies
+  try {
+    execSync("npm install --save resend dotenv express", {
+      cwd,
+      stdio: "inherit",
+    });
+    console.log();
+    console.log(chalk.green("✓") + " Dependencies installed");
+  } catch (e) {
+    console.log(chalk.yellow("⚠") + " Failed to install dependencies. Run manually:");
+    console.log(chalk.dim("  npm install resend dotenv express"));
+  }
+
+  console.log();
+  console.log(chalk.bold("Checking Cursor CLI..."));
+  console.log();
+
+  // Check Cursor CLI
+  await checkCursorCli();
+
+  // Final instructions
+  console.log();
+  console.log(chalk.dim("─".repeat(60)));
+  console.log(chalk.bold.green("Setup complete!"));
+  console.log();
+  console.log("Next steps:");
+  console.log();
+  console.log(chalk.dim("1.") + " Configure Resend webhook to point to your ngrok URL:");
+  console.log(chalk.cyan("   npx cursorbyemail start"));
+  console.log();
+  console.log(chalk.dim("2.") + " In Resend dashboard, add webhook endpoint:");
+  console.log(chalk.dim("   https://<your-ngrok-url>/inbound/resend"));
+  console.log();
+  console.log(chalk.dim("3.") + " Start using Cursor - emails will be sent on agent completion");
+  console.log(chalk.dim("   and replies will resume the conversation."));
+  console.log();
+}

package/lib/start.js

@@ -0,0 +1,132 @@
+import "dotenv/config";
+import chalk from "chalk";
+import ngrok from "ngrok";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export async function start({ port = 8787 } = {}) {
+  const webhookPort = process.env.WEBHOOK_PORT || port;
+  
+  console.log();
+  console.log(chalk.bold("cursorbyemail") + " - Starting webhook server");
+  console.log(chalk.dim("─".repeat(60)));
+  console.log();
+
+  // Find webhook script
+  const cwd = process.cwd();
+  const webhookPaths = [
+    join(cwd, ".cursor", "hooks", "webhook.mjs"),
+    join(cwd, "webhook.mjs"),
+  ];
+
+  let webhookPath = null;
+  for (const p of webhookPaths) {
+    if (existsSync(p)) {
+      webhookPath = p;
+      break;
+    }
+  }
+
+  if (!webhookPath) {
+    console.log(chalk.red("✗ webhook.mjs not found"));
+    console.log(chalk.dim("  Run 'npx cursorbyemail init' first to set up your project"));
+    process.exit(1);
+  }
+
+  console.log(chalk.dim(`Using webhook: ${webhookPath}`));
+  console.log();
+
+  // Start Express server
+  console.log(chalk.bold("Starting webhook server..."));
+  
+  const serverProcess = spawn("node", [webhookPath], {
+    env: { ...process.env, WEBHOOK_PORT: String(webhookPort) },
+    stdio: ["inherit", "pipe", "pipe"],
+    cwd,
+  });
+
+  serverProcess.stdout.on("data", (data) => {
+    process.stdout.write(chalk.dim(`[server] ${data}`));
+  });
+
+  serverProcess.stderr.on("data", (data) => {
+    process.stderr.write(chalk.red(`[server] ${data}`));
+  });
+
+  serverProcess.on("error", (err) => {
+    console.log(chalk.red(`✗ Failed to start server: ${err.message}`));
+    process.exit(1);
+  });
+
+  // Wait for server to start
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+
+  console.log(chalk.green("✓") + ` Webhook server running on port ${webhookPort}`);
+  console.log();
+
+  // Start ngrok tunnel
+  console.log(chalk.bold("Starting ngrok tunnel..."));
+  
+  try {
+    const ngrokOptions = {
+      addr: webhookPort,
+      proto: "http",
+    };
+
+    // Use auth token from env if available
+    if (process.env.NGROK_AUTHTOKEN) {
+      ngrokOptions.authtoken = process.env.NGROK_AUTHTOKEN;
+    }
+
+    const url = await ngrok.connect(ngrokOptions);
+    
+    console.log(chalk.green("✓") + " ngrok tunnel established");
+    console.log();
+    console.log(chalk.dim("─".repeat(60)));
+    console.log();
+    console.log(chalk.bold("Webhook URL:"));
+    console.log(chalk.cyan.bold(`  ${url}/inbound/resend`));
+    console.log();
+    console.log(chalk.dim("Add this URL to your Resend webhook configuration:"));
+    console.log(chalk.dim("  1. Go to Resend dashboard → Webhooks"));
+    console.log(chalk.dim("  2. Add endpoint with URL above"));
+    console.log(chalk.dim("  3. Select 'email.received' event"));
+    console.log();
+    console.log(chalk.dim("Press Ctrl+C to stop"));
+    console.log();
+
+  } catch (err) {
+    console.log(chalk.red(`✗ Failed to start ngrok: ${err.message}`));
+    console.log();
+    
+    if (err.message.includes("authtoken")) {
+      console.log(chalk.dim("To fix this:"));
+      console.log(chalk.dim("  1. Get your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken"));
+      console.log(chalk.dim("  2. Add NGROK_AUTHTOKEN to your .env file"));
+      console.log(chalk.dim("  Or run: ngrok config add-authtoken <token>"));
+    }
+    
+    serverProcess.kill();
+    process.exit(1);
+  }
+
+  // Handle shutdown
+  const shutdown = async () => {
+    console.log();
+    console.log(chalk.dim("Shutting down..."));
+    
+    try {
+      await ngrok.disconnect();
+      await ngrok.kill();
+    } catch (e) {
+      // Ignore ngrok shutdown errors
+    }
+    
+    serverProcess.kill();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "cursorbyemail",
+	"version": "0.5.0",
+	"description": "Email-based conversations with Cursor agents via Resend webhooks and ngrok tunneling",
+	"type": "module",
+	"bin": {
+		"cursorbyemail": "bin/cli.js"
+	},
+	"main": "lib/index.js",
+	"scripts": {
+		"start": "node lib/start.js"
+	},
+	"keywords": [
+		"cursor",
+		"email",
+		"agent",
+		"resend",
+		"ngrok",
+		"webhook",
+		"ai",
+		"automation"
+	],
+	"author": "",
+	"license": "MIT",
+	"dependencies": {
+		"chalk": "^5.3.0",
+		"commander": "^12.1.0",
+		"dotenv": "^16.4.5",
+		"express": "^4.21.0",
+		"ngrok": "^5.0.0-beta.2",
+		"prompts": "^2.4.2",
+		"resend": "^4.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"files": [
+		"bin/",
+		"lib/",
+		"templates/"
+	],
+	"repository": {
+		"type": "git",
+		"url": ""
+	}
+}

package/templates/beautify-transcript-email-html.js

@@ -0,0 +1,322 @@
+/**
+ * Beautify a Cursor transcript (raw text) into HTML suitable for email.
+ * - Handles "user:" / "assistant:" turns
+ * - Renders <user_query> blocks
+ * - Renders <code_selection ...> blocks with header + line numbers
+ * - Collapses <attached_files> placeholder
+ * - Escapes HTML, preserves spacing, wraps long code lines
+ *
+ * Usage:
+ *   const html = beautifyTranscriptToEmailHTML(transcriptText, { title: "Cursor Agent Result" });
+ */
+
+const css = `
+  :root{color-scheme:light}
+  body{margin:0;padding:0;background:#ffffff;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Arial}
+  .wrap{max-width:900px;margin:0 auto;padding:24px}
+  .card{border:1px solid #e5e7eb;border-radius:12px;overflow:hidden;background:#fff}
+  .card + .card{margin-top:18px}
+  .hdr{padding:16px 18px;border-bottom:1px solid #e5e7eb;background:#f9fafb}
+  .hdr h1{margin:0;font-size:16px;line-height:1.3;font-weight:700;color:#111827}
+  .hdr .meta{margin-top:6px;font-size:12px;color:#6b7280}
+  .turn{padding:16px 18px;border-top:1px solid #f3f4f6}
+  .turn:first-child{border-top:none}
+  .role{display:inline-block;font-size:11px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;padding:4px 8px;border-radius:999px}
+  .role.user{background:#eff6ff;color:#1d4ed8}
+  .role.assistant{background:#ecfdf5;color:#047857}
+  .content{margin-top:10px;font-size:13px;line-height:1.55;color:#111827}
+  .p{margin:10px 0}
+  .muted{color:#6b7280}
+  .box{border:1px solid #e5e7eb;border-radius:10px;background:#fafafa;padding:12px;margin:12px 0}
+  .qtitle{font-size:12px;font-weight:700;color:#111827;margin:0 0 8px 0}
+  .codehdr{display:flex;gap:10px;flex-wrap:wrap;align-items:center;margin-bottom:8px}
+  .badge{font-size:11px;background:#f3f4f6;color:#111827;border:1px solid #e5e7eb;border-radius:999px;padding:3px 8px}
+  pre{margin:0;white-space:pre-wrap;word-break:break-word;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:12px;line-height:1.5;color:#0f172a}
+  .lines{counter-reset:ln}
+  .ln{display:block}
+  .ln:before{counter-increment:ln;content:counter(ln);display:inline-block;width:2.7em;margin-right:12px;text-align:right;color:#94a3b8}
+  .raw{margin-top:18px;border-top:1px dashed #e5e7eb;padding-top:14px}
+  .raw h2{margin:0 0 8px 0;font-size:12px;color:#6b7280;font-weight:700}
+`.trim();
+
+const esc = (s) =>
+	String(s)
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
+
+const safeJson = (obj) => {
+	try {
+		return JSON.stringify(obj, null, 2);
+	} catch {
+		return String(obj);
+	}
+};
+
+const normalizeNewlines = (text) => String(text ?? "").replace(/\r\n/g, "\n");
+
+const splitTurns = (src) => {
+	const turns = [];
+	const re = /^(user|assistant):[ \t]*$/gim;
+	let lastIndex = 0;
+	let m;
+	let currentRole = null;
+
+	while ((m = re.exec(src)) !== null) {
+		const role = m[1].toLowerCase();
+		const markerStart = m.index;
+		if (currentRole !== null) {
+			const chunk = src.slice(lastIndex, markerStart).trim();
+			turns.push({ role: currentRole, text: chunk });
+		}
+		currentRole = role;
+		lastIndex = re.lastIndex;
+	}
+	if (currentRole !== null) {
+		turns.push({ role: currentRole, text: src.slice(lastIndex).trim() });
+	} else {
+		turns.push({ role: "assistant", text: src.trim() });
+	}
+
+	return turns;
+};
+
+const renderInlineBlocks = (text) => {
+	let t = String(text ?? "");
+
+	// Replace <attached_files> placeholder
+	t = t.replace(/<attached_files>\s*<\/attached_files>|<attached_files>\s*/gi, "\n[attached_files]\n");
+
+	// Extract <user_query> blocks
+	const uq = [];
+	t = t.replace(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/gi, (_, inner) => {
+		uq.push(inner.trim());
+		return "\n{{{__USER_QUERY__}}}\n";
+	});
+
+	// Extract <code_selection ...> blocks
+	const codeSelections = [];
+	t = t.replace(
+		/<code_selection\b([^>]*)>\s*([\s\S]*?)\s*<\/code_selection>/gi,
+		(_, attrs, inner) => {
+			const pathMatch = attrs.match(/\bpath="([^"]+)"/i);
+			const linesMatch = attrs.match(/\blines="([^"]+)"/i);
+			codeSelections.push({
+				path: pathMatch ? pathMatch[1] : "",
+				lines: linesMatch ? linesMatch[1] : "",
+				code: inner.replace(/\s+$/g, ""),
+			});
+			return "\n{{{__CODE_SELECTION__}}}\n";
+		}
+	);
+
+	// Escape everything, then re-inject safe HTML blocks.
+	const parts = esc(t).split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
+
+	const blocks = [];
+	let uqIdx = 0;
+	let csIdx = 0;
+
+	for (const p of parts) {
+		if (p.includes("{{{__USER_QUERY__}}}")) {
+			const q = uq[uqIdx++] ?? "";
+			blocks.push(`
+		<div class="box">
+		  <div class="qtitle">User query</div>
+		  <div class="content"><pre>${esc(q)}</pre></div>
+		</div>
+	  `.trim());
+			continue;
+		}
+		if (p.includes("{{{__CODE_SELECTION__}}}")) {
+			const cs = codeSelections[csIdx++] ?? { path: "", lines: "", code: "" };
+
+			// Parse line-numbered code like "100| ..."
+			const rawLines = String(cs.code ?? "").split("\n");
+			const normalized = rawLines
+				.map((ln) => ln.replace(/^\s*\d+\|\s?/, ""))
+				.join("\n")
+				.trimEnd();
+
+			blocks.push(`
+		<div class="box">
+		  <div class="codehdr">
+			${cs.path ? `<span class="badge">${esc(cs.path)}</span>` : ""}
+			${cs.lines ? `<span class="badge">lines ${esc(cs.lines)}</span>` : ""}
+		  </div>
+		  <pre class="lines">${esc(normalized)
+					.split("\n")
+					.map((line) => `<span class="ln">${line || " "}</span>`)
+					.join("\n")}</pre>
+		</div>
+	  `.trim());
+			continue;
+		}
+
+		blocks.push(`<div class="p"><pre>${p}</pre></div>`);
+	}
+
+	return blocks.join("\n");
+};
+
+const renderTurns = (transcript) => {
+	const src = normalizeNewlines(transcript);
+	const turns = splitTurns(src);
+
+	return turns
+		.filter((t) => t.text && t.text.length)
+		.map((t) => {
+			const roleClass = t.role === "user" ? "user" : "assistant";
+			return `
+		  <div class="turn">
+			<span class="role ${roleClass}">${esc(t.role)}</span>
+			<div class="content">
+			  ${renderInlineBlocks(t.text)}
+			</div>
+		  </div>
+		`.trim();
+		})
+		.join("\n");
+};
+
+const renderCard = ({ title, metaLines = [], bodyHtml }) => {
+	const meta = metaLines
+		.filter(Boolean)
+		.map((line) => `<div class="meta">${esc(line)}</div>`)
+		.join("");
+
+	return `
+	  <div class="card">
+		<div class="hdr">
+		  <h1>${esc(title)}</h1>
+		  ${meta}
+		</div>
+		${bodyHtml}
+	  </div>
+	`.trim();
+};
+
+const renderDocument = ({ cardsHtml, rawFallback = "" }) => `
+  <!doctype html>
+  <html>
+	<head>
+	  <meta charset="utf-8" />
+	  <meta name="viewport" content="width=device-width,initial-scale=1" />
+	  <style>${css}</style>
+	</head>
+	<body>
+	  <div class="wrap">
+		${cardsHtml}
+		${rawFallback}
+	  </div>
+	</body>
+  </html>
+`.trim();
+
+export function extractLatestResponseFromPayload(payload, rawFallback = "") {
+	const candidates = [
+		payload?.text,
+		payload?.finalResponse,
+		payload?.response,
+		payload?.message,
+		payload?.summary,
+		payload?.output,
+	];
+
+	for (const c of candidates) {
+		if (!c) continue;
+		if (typeof c === "string") return c;
+		return safeJson(c);
+	}
+
+	return rawFallback || "";
+}
+
+export function getTranscriptPathFromPayload(payload) {
+	return payload?.transcript_path || payload?.transcriptPath || "";
+}
+
+export function beautifyTranscriptToEmailHTML(
+	transcript,
+	{
+		title = "Agent transcript",
+		includeRawFallback = true,
+		maxRawFallbackChars = 15000,
+	} = {}
+) {
+	const src = normalizeNewlines(transcript);
+	const renderedTurns = renderTurns(src);
+
+	const card = renderCard({
+		title,
+		metaLines: [new Date().toISOString()],
+		bodyHtml:
+			renderedTurns ||
+			`<div class="turn"><div class="content muted">No transcript content.</div></div>`,
+	});
+
+	const rawFallback =
+		includeRawFallback && src
+			? `
+		  <div class="raw">
+			<h2>Raw transcript (truncated)</h2>
+			<pre>${esc(src.slice(0, maxRawFallbackChars))}${
+				src.length > maxRawFallbackChars ? "\n...(truncated)" : ""
+			}</pre>
+		  </div>
+		`.trim()
+			: "";
+
+	return renderDocument({ cardsHtml: card, rawFallback });
+}
+
+export function beautifyPayloadToEmailHTML(
+	payload,
+	{
+		title = "Cursor agent finished",
+		includeRawFallback = true,
+		maxRawFallbackChars = 15000,
+		transcriptText = "",
+		latestResponse,
+		transcriptPath,
+	} = {}
+) {
+	const responseText = latestResponse ?? extractLatestResponseFromPayload(payload);
+	const fullTranscript = transcriptText ?? payload?.transcript ?? "";
+	const path = transcriptPath ?? getTranscriptPathFromPayload(payload);
+	const now = new Date().toISOString();
+
+	const responseTurns = renderTurns(`assistant:\n${responseText || ""}`);
+	const responseCard = renderCard({
+		title: "Latest response",
+		metaLines: [now],
+		bodyHtml:
+			responseTurns ||
+			`<div class="turn"><div class="content muted">No latest response.</div></div>`,
+	});
+
+	const transcriptTurns = renderTurns(fullTranscript);
+	const transcriptCard = renderCard({
+		title: title || "Full transcript",
+		metaLines: [now, path ? `Transcript path: ${path}` : "Transcript path: (missing)"],
+		bodyHtml:
+			transcriptTurns ||
+			`<div class="turn"><div class="content muted">No transcript content.</div></div>`,
+	});
+
+	const rawFallback =
+		includeRawFallback && fullTranscript
+			? `
+		  <div class="raw">
+			<h2>Raw transcript (truncated)</h2>
+			<pre>${esc(fullTranscript.slice(0, maxRawFallbackChars))}${
+				fullTranscript.length > maxRawFallbackChars ? "\n...(truncated)" : ""
+			}</pre>
+		  </div>
+		`.trim()
+			: "";
+
+	return renderDocument({ cardsHtml: [responseCard, transcriptCard].join("\n"), rawFallback });
+}

package/templates/email-on-stop.mjs

@@ -0,0 +1,110 @@
+import "dotenv/config";
+import { Resend } from "resend";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	beautifyPayloadToEmailHTML,
+	extractLatestResponseFromPayload,
+	getTranscriptPathFromPayload,
+} from "./beautify-transcript-email-html.js";
+
+const LOG_FILE = process.env.CURSOR_HOOK_LOG_FILE || ".cursor/hooks/hook.log";
+const DEBUG = process.env.CURSOR_HOOK_DEBUG === "1";
+
+function log(line) {
+	const ts = new Date().toISOString();
+	fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+	fs.appendFileSync(LOG_FILE, `[${ts}] ${line}\n`, "utf8");
+}
+
+function readStdin() {
+	return new Promise((resolve) => {
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => (data += chunk));
+		process.stdin.on("end", () => resolve(data));
+	});
+}
+
+function safeJson(obj) {
+	try { return JSON.stringify(obj, null, 2); } catch { return String(obj); }
+}
+
+function readTranscriptFile(transcriptPath) {
+	if (!transcriptPath) return "";
+	try {
+		return fs.readFileSync(transcriptPath, "utf8");
+	} catch (e) {
+		log(`Transcript read error: ${e?.message || e}`);
+		return "";
+	}
+}
+
+async function main() {
+	log("Hook start");
+
+	const enabled = process.env.CURSOR_EMAIL_ON_FINISH === "1";
+	if (!enabled) {
+		log("CURSOR_EMAIL_ON_FINISH!=1 -> exit");
+		process.exit(0);
+	}
+
+	const raw = await readStdin();
+	log(`stdin bytes=${Buffer.byteLength(raw || "", "utf8")}`);
+
+	let payload = {};
+	try {
+		payload = raw ? JSON.parse(raw) : {};
+	} catch (e) {
+		log(`JSON parse error: ${e?.message || e}`);
+		if (DEBUG) log(`RAW:\n${raw}`);
+		process.exit(1);
+	}
+
+	if (DEBUG) log(`PAYLOAD:\n${safeJson(payload)}`);
+
+	const to = process.env.CURSOR_EMAIL_TO;
+	const from = process.env.RESEND_FROM;
+	const replyTo = process.env.RESEND_REPLY_TO;
+	const apiKey = process.env.RESEND_API_KEY;
+
+	if (!to || !from || !apiKey) {
+		log("Missing env vars: CURSOR_EMAIL_TO / RESEND_FROM / RESEND_API_KEY");
+		process.exit(1);
+	}
+
+	const baseSubject = process.env.CURSOR_EMAIL_SUBJECT ?? "Cursor agent finished";
+	const conversationId = payload?.conversation_id || payload?.conversationId || "";
+	const subject = conversationId
+		? `${baseSubject} [${conversationId}]`
+		: baseSubject;
+	const text = extractLatestResponseFromPayload(payload, raw || "(empty hook payload)");
+	const transcriptPath = getTranscriptPathFromPayload(payload);
+	const transcriptText = readTranscriptFile(transcriptPath);
+	const html = beautifyPayloadToEmailHTML(payload, {
+		title: "Full transcript",
+		transcriptText,
+		latestResponse: text,
+		transcriptPath,
+	});
+
+	if (process.env.CURSOR_DRY_RUN === "1") {
+		log(`DRY_RUN=1 subject="${subject}" to="${to}" from="${from}" body_len=${text.length} html_len=${html.length}`);
+		process.exit(0);
+	}
+
+	const resend = new Resend(apiKey);
+	const result = await resend.emails.send({ from, to, subject, text, html, replyTo });
+
+	if (result?.error) {
+		log(`Resend error: ${safeJson(result.error)}`);
+		process.exit(1);
+	}
+
+	log(`Sent ok id=${result?.data?.id || "unknown"}`);
+}
+
+main().catch((e) => {
+	log(`Unhandled: ${e?.stack || e}`);
+	process.exit(1);
+});

package/templates/hooks.json

@@ -0,0 +1,10 @@
+{
+	"version": 1,
+	"hooks": {
+		"afterAgentResponse": [
+			{
+				"command": "npm run -s cursor:email-hook"
+			}
+		]
+	}
+}

package/templates/webhook.mjs

@@ -0,0 +1,150 @@
+import "dotenv/config";
+import express from "express";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Resend } from "resend";
+
+const execFileAsync = promisify(execFile);
+const app = express();
+app.use(express.json({ limit: "2mb" }));
+
+// Map job ID to repository path (customize as needed)
+function jobIdToRepoPath(jobId) {
+	// Default to current workspace; extend with a lookup table if needed
+	const mapping = {
+		// "job123": "/path/to/repo",
+	};
+	return mapping[jobId] || process.env.DEFAULT_REPO_PATH || process.cwd();
+}
+
+// Extract email address from "Name <email>" format
+function extractEmail(from) {
+	const match = from.match(/<([^>]+)>/);
+	return match ? match[1] : from;
+}
+
+// Render CLI output as HTML
+function renderResultHtml(stdout) {
+	const escaped = stdout
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+	return `<pre style="font-family:monospace;white-space:pre-wrap;">${escaped}</pre>`;
+}
+
+function stripQuotedReply(text = "") {
+	// Remove quoted lines and email citation headers (English and Spanish)
+	return text
+		.split("\n")
+		.filter((l) => !l.trim().startsWith(">"))
+		.join("\n")
+		.split(/\n\nOn .*wrote:\n/i)[0]          // English: "On ... wrote:"
+		.split(/\n\nEl [^,]+,.*escribió:\n/i)[0] // Spanish: "El mié, 4 feb 2026...escribió:"
+		.split(/\n\nEl [^,]+,/)[0]               // Spanish fallback: cut at "El día,"
+		.trim();
+}
+
+app.post("/inbound/resend", async (req, res) => {
+	try {
+		const dryRun = req.query.dryRun === "true" || process.env.DRY_RUN === "true";
+
+		if (dryRun) {
+			console.log("Payload received:", JSON.stringify(req.body, null, 2));
+		}
+
+		// Resend inbound event payload includes the parsed email metadata.
+		const event = req.body;
+		const data = event?.data || {};
+		const emailId = data?.email_id;
+
+		// Fetch full email content via Resend Receiving API
+		const resendClient = new Resend(process.env.RESEND_API_KEY);
+
+		if (dryRun) {
+			console.log("Email ID from webhook:", emailId);
+		}
+
+		// Use receiving API for inbound emails
+		const fullEmail = await resendClient.emails.receiving.get(emailId);
+
+		if (dryRun) {
+			console.log("Full email received");
+		}
+
+		const subject = data?.subject || "";
+		const to = (data?.to && data.to[0]) || "";
+		const from = data?.from || "";
+
+		// correlation: extract job ID (UUID) from subject like "[dcbd565f-6540-4794-b5e9-6e514346faa4]"
+		const m = subject.match(/\[([a-f0-9-]{36})\]/i);
+		if (!m) return res.status(200).json({ ok: true, ignored: "no job id" });
+		const jobId = m[1];
+
+		// Use text from Receiving API response
+		const replyText = stripQuotedReply(fullEmail.data?.text || "");
+
+		const repoPath = jobIdToRepoPath(jobId);
+		const prompt = replyText;
+
+		const cursorArgs = ["agent", "--resume", jobId, "--print", "--output-format", "json", prompt];
+		const cursorCommand = {
+			command: "cursor",
+			args: cursorArgs,
+			cwd: repoPath,
+			full: `cursor agent --resume ${jobId} --print --output-format json ${JSON.stringify(prompt)}`,
+		};
+
+		// Always print the command
+		console.log("Cursor command:", cursorCommand.full);
+
+		if (dryRun) {
+			return res.json({
+				ok: true,
+				dryRun: true,
+				parsed: {
+					jobId,
+					from,
+					to,
+					subject,
+					replyText,
+					repoPath,
+				},
+				cursorCommand,
+				email: {
+					from: process.env.RESEND_FROM,
+					to: extractEmail(from),
+					subject,
+				},
+			});
+		}
+
+		// Run Cursor CLI
+		const { stdout } = await execFileAsync(
+			cursorCommand.command,
+			cursorCommand.args,
+			{ cwd: cursorCommand.cwd, timeout: 10 * 60 * 1000 }
+		);
+
+		await resendClient.emails.send({
+			from: process.env.RESEND_FROM,
+			to: extractEmail(from),
+			subject,
+			html: renderResultHtml(stdout),
+		});
+
+		res.json({ ok: true });
+	} catch (e) {
+		console.error("Webhook error:", e);
+		res.status(500).json({ ok: false, error: e.message });
+	}
+});
+
+// Health check endpoint
+app.get("/health", (req, res) => {
+	res.json({ ok: true, timestamp: new Date().toISOString() });
+});
+
+const port = process.env.WEBHOOK_PORT || 8787;
+app.listen(port, () => {
+	console.log(`Webhook server listening on port ${port}`);
+});