@hogsend/engine 0.3.0 → 0.5.0

package/src/lib/boot.ts

@@ -0,0 +1,166 @@
+import { createRequire } from "node:module";
+import color from "picocolors";
+import type { HogsendClient } from "../container.js";
+import { API_VERSION } from "../env.js";
+
+/**
+ * Engine-owned boot output. ONE place renders the "we're up" message for the
+ * API and the worker, so every scaffolded `create-hogsend` app gets the same
+ * polished startup for free — the entry points just call these.
+ *
+ * Two modes, picked from the environment (never a flag):
+ *  - banner: a branded, minimal box (the `create-hogsend` look — magenta badge,
+ *    ✓ checks, cyan links) printed straight to stdout. Only when stdout is a TTY
+ *    AND `NODE_ENV === "development"`, i.e. an interactive `pnpm dev`.
+ *  - structured: a single `logger.info("… ready", { … })` line. Everywhere else
+ *    (production, CI, piped output, tests) so log scraping stays intact.
+ *
+ * The scattered `registry loaded` / `studio mounted` / `server running` lines
+ * are demoted to `debug`; this banner is the single source of truth on boot.
+ */
+
+// Last-resort value when the runtime manifest read below fails (e.g. a pruned
+// node_modules behind a bundler). The read is authoritative in every normal dev
+// run and deploy, so this is effectively never hit — `"unknown"` keeps it honest
+// rather than risking a stale hard-coded version slipping into structured logs.
+const FALLBACK_ENGINE_VERSION = "unknown";
+
+// Conventional Vite dev-server origin for the Studio package (`pnpm dev` starts
+// it). In production the Studio is served by the API at `${API_PUBLIC_URL}/studio`.
+const STUDIO_DEV_URL = "http://localhost:5173";
+const DOCS_URL = "https://docs.hogsend.com";
+
+let cachedEngineVersion: string | undefined;
+
+/** The running `@hogsend/engine` package version (e.g. "0.4.0"). */
+export function getEngineVersion(): string {
+  if (cachedEngineVersion) return cachedEngineVersion;
+  try {
+    // Resolve the engine's own manifest from the consumer's module graph —
+    // correct under tsx (workspace symlink) and a bundled deploy alike. Needs
+    // `"./package.json"` in this package's `exports`.
+    const require = createRequire(import.meta.url);
+    const pkg = require("@hogsend/engine/package.json") as { version?: string };
+    cachedEngineVersion = pkg.version ?? FALLBACK_ENGINE_VERSION;
+  } catch {
+    cachedEngineVersion = FALLBACK_ENGINE_VERSION;
+  }
+  return cachedEngineVersion;
+}
+
+const BADGE = color.bgMagenta(color.black(" hogsend "));
+
+/** Interactive `pnpm dev` in a real terminal — the only place the banner shows. */
+function bannerMode(client: HogsendClient): boolean {
+  return Boolean(process.stdout.isTTY) && client.env.NODE_ENV === "development";
+}
+
+function plural(n: number, word: string): string {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+
+function writeBanner(lines: (string | null)[]): void {
+  const body = lines.filter((l): l is string => l !== null).join("\n");
+  process.stdout.write(`\n${body}\n\n`);
+}
+
+export interface ApiReadyInfo {
+  client: HogsendClient;
+  /** The port the HTTP server bound to. */
+  port: number;
+  /** Applied engine-track schema version, when the boot guard ran. */
+  schemaVersion?: string | null;
+}
+
+/** Render the API "ready" output (banner in dev TTY, structured log otherwise). */
+export function reportApiReady(info: ApiReadyInfo): void {
+  const { client, port } = info;
+  const engineVersion = getEngineVersion();
+  const journeys = client.registry.count();
+  const buckets = client.bucketRegistry.count();
+  const templates = Object.keys(client.templates).length;
+  const localUrl = `http://localhost:${port}`;
+
+  if (!bannerMode(client)) {
+    client.logger.info("Hogsend API ready", {
+      engineVersion,
+      apiVersion: API_VERSION,
+      port,
+      url: client.env.API_PUBLIC_URL,
+      journeys,
+      buckets,
+      templates,
+      schema: info.schemaVersion ?? undefined,
+    });
+    return;
+  }
+
+  const dim = color.dim;
+  const ok = color.green("✓");
+  const loaded = [
+    plural(journeys, "journey"),
+    plural(buckets, "bucket"),
+    plural(templates, "template"),
+  ].join(dim(" · "));
+  const label = (text: string) => dim(text.padEnd(7));
+
+  writeBanner([
+    `${BADGE} ${dim(`engine ${engineVersion} · api ${API_VERSION}`)}`,
+    "",
+    `  ${ok} ${loaded}`,
+    info.schemaVersion
+      ? `  ${ok} schema in sync ${dim(`(${info.schemaVersion})`)}`
+      : null,
+    "",
+    `  ${label("API")}${color.cyan(localUrl)}`,
+    `  ${label("Docs")}${color.cyan(`${localUrl}/docs`)}`,
+    `  ${label("Studio")}${color.cyan(STUDIO_DEV_URL)}`,
+    `  ${label("Guides")}${color.cyan(DOCS_URL)}`,
+    "",
+    `  ${dim("Next")}  fire a test event in ${color.cyan("Studio › Debug")} ${dim("·")} run the worker: ${color.cyan("pnpm worker:dev")}`,
+  ]);
+}
+
+export interface WorkerReadyInfo {
+  client: HogsendClient;
+  journeyTasks: number;
+  bucketTasks: number;
+  builtinTasks: number;
+}
+
+/** Render the worker "ready" output (banner in dev TTY, structured log otherwise). */
+export function reportWorkerReady(info: WorkerReadyInfo): void {
+  const { client, journeyTasks, bucketTasks, builtinTasks } = info;
+  const engineVersion = getEngineVersion();
+  const hatchetHost = client.env.HATCHET_CLIENT_HOST_PORT;
+
+  if (!bannerMode(client)) {
+    client.logger.info("Hogsend worker ready", {
+      engineVersion,
+      hatchet: hatchetHost,
+      namespace: client.env.HATCHET_CLIENT_NAMESPACE || undefined,
+      journeyTasks,
+      bucketTasks,
+      builtinTasks,
+    });
+    return;
+  }
+
+  const dim = color.dim;
+  const ok = color.green("✓");
+  const tasks = [
+    plural(journeyTasks, "journey task"),
+    plural(bucketTasks, "bucket task"),
+    plural(builtinTasks, "built-in task"),
+  ].join(dim(" · "));
+
+  writeBanner([
+    `${BADGE} ${dim(`worker · engine ${engineVersion}`)}`,
+    "",
+    `  ${ok} registered on Hatchet ${dim(`(${hatchetHost})`)}`,
+    `  ${ok} ${tasks}`,
+    "",
+    `  ${dim("Listening — journeys fire as events arrive.")}`,
+    `  ${dim("Send one:")} ${color.cyan("POST /v1/ingest")} ${dim("· or Studio › Debug")}`,
+  ]);
+}

package/src/lib/bucket-posthog-sync.ts

@@ -1,12 +1,12 @@
 import type { BucketMeta } from "@hogsend/core";
+import { getAnalytics } from "./analytics-singleton.js";
 import type { Logger } from "./logger.js";
-import { getPostHog } from "./posthog.js";
 
 /**
  * Optional PostHog person-property mirror for a bucket transition (Section 12).
  *
  * OFF BY DEFAULT — a no-op unless `meta.syncToPostHog === true`. Also a no-op
- * without `POSTHOG_API_KEY` (`getPostHog()` returns undefined), so self-host
+ * without `POSTHOG_API_KEY` (the injected analytics is undefined), so self-host
  * setups that omit PostHog silently do nothing — documented, not broken.
  *
  * On JOIN it `$set`s a boolean person property `true`; on LEAVE it `$unset`s the
@@ -32,8 +32,10 @@ export function syncBucketToPostHog(opts: {
 
   if (!bucket.syncToPostHog) return;
 
-  const posthog = getPostHog();
-  if (!posthog) return; // no POSTHOG_API_KEY → silent no-op
+  // The injected analytics instance (set by createHogsendClient). Same object as
+  // container.analytics; undefined when POSTHOG_API_KEY is unset.
+  const posthog = getAnalytics();
+  if (!posthog) return; // no analytics configured → silent no-op
 
   const propertyKey =
     bucket.postHogPropertyKey ?? `hogsend_bucket_${bucket.id}`;

package/src/lib/email-service-types.ts

@@ -1,4 +1,11 @@
-import type { DurationObject } from "@hogsend/core";
+import type {
+  BatchEmailItem,
+  DurationObject,
+  SendEmailOptions,
+  SendResult,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/core";
 import type {
   EmailServiceRenderOptions,
   EmailServiceRenderResult,
@@ -7,20 +14,22 @@ import type {
   TemplateRegistry,
   TemplateRegistryMap,
 } from "@hogsend/email";
-import type {
-  BatchEmailItem,
-  SendEmailOptions,
-  SendResult,
-  WebhookEventType,
-  WebhookHandlerMap,
-} from "@hogsend/plugin-resend";
 import type { Logger } from "./logger.js";
 
 export type {
   BatchEmailItem,
   SendEmailOptions,
   SendResult,
-} from "@hogsend/plugin-resend";
+} from "@hogsend/core";
+
+/**
+ * Input to the mailer's low-level {@link EmailService.sendRaw}: the provider
+ * contract's `SendEmailOptions`, but `from` is optional — the mailer resolves it
+ * from `config.defaultFrom` when absent (see `resolveFrom` in mailer.ts). The
+ * wire contract keeps `from` required because the provider always receives a
+ * resolved address.
+ */
+export type SendRawOptions = Omit<SendEmailOptions, "from"> & { from?: string };
 
 // ---------------------------------------------------------------------------
 // Tracked email (high-level API)
@@ -136,7 +145,7 @@ export interface EmailService {
     options: EmailServiceSendOptions<K>,
   ): Promise<TrackedSendResult>;
 
-  sendRaw(options: SendEmailOptions): Promise<SendResult>;
+  sendRaw(options: SendRawOptions): Promise<SendResult>;
 
   sendBatch(options: { emails: BatchEmailItem[] }): Promise<{
     results: SendResult[];

package/src/lib/email.ts

@@ -3,21 +3,23 @@ import type {
   EmailService,
   EmailServiceSendOptions,
 } from "./email-service-types.js";
+import { createSingleton } from "./singleton.js";
 
-let _service: EmailService | null = null;
+const _service = createSingleton<EmailService>("Email service");
 
-export function setEmailService(service: EmailService): void {
-  _service = service;
-}
+export const setEmailService = _service.set;
 
-function getService(): EmailService {
-  if (!_service) {
-    throw new Error(
-      "Email service not initialized. Call setEmailService() at startup.",
-    );
-  }
-  return _service;
-}
+/**
+ * The injected {@link EmailService} (set by `createHogsendClient` →
+ * `setEmailService`). Exposed so module-level task-execution sites with no
+ * client reference (the `send-email` Hatchet task, the alerting task) deliver
+ * through the same provider-backed mailer the container built, honoring a
+ * swapped provider instead of constructing a raw Resend client of their own.
+ * Throws if read before the container has installed the service — same
+ * guarantee as the journey/bucket registry singletons (the container always
+ * runs first in both the API and worker processes).
+ */
+export const getEmailService = _service.get;
 
 export interface SendEmailOptions {
   to: string;
@@ -37,7 +39,7 @@ export interface SendEmailResult {
 export async function sendEmail(
   opts: SendEmailOptions,
 ): Promise<SendEmailResult> {
-  const service = getService();
+  const service = getEmailService();
 
   let unsubscribeUrl: string | undefined;
   if (process.env.API_PUBLIC_URL && process.env.BETTER_AUTH_SECRET) {

package/src/lib/ingestion.ts

@@ -76,7 +76,7 @@ export async function ingestEvent(opts: {
       userEmail: event.userEmail,
       properties: serializableProperties,
     }),
-    checkExits(db, registry, {
+    checkExits(db, registry, hatchet, logger, {
       userId: event.userId,
       eventName: event.event,
       properties: event.properties,
@@ -130,6 +130,8 @@ export async function ingestEvent(opts: {
 async function checkExits(
   db: Database,
   registry: JourneyRegistry,
+  hatchet: HatchetClient,
+  logger: Logger,
   event: {
     userId: string;
     eventName: string;
@@ -147,6 +149,7 @@ async function checkExits(
   });
 
   const statesToExit: string[] = [];
+  const runIdsToCancel: string[] = [];
 
   for (const state of activeStates) {
     const journey = registry.get(state.journeyId);
@@ -163,6 +166,9 @@ async function checkExits(
 
     if (shouldExit) {
       statesToExit.push(state.id);
+      if (state.hatchetRunId) {
+        runIdsToCancel.push(state.hatchetRunId);
+      }
     }
 
     results.push({
@@ -181,6 +187,21 @@ async function checkExits(
         updatedAt: new Date(),
       })
       .where(inArray(journeyStates.id, statesToExit));
+
+    // Cancel the live durable runs so a journey suspended in a sleep or
+    // `waitForEvent` can't resume and fire after it has exited. Best-effort: a
+    // run may have already finished, and the in-run resume guard
+    // (JourneyExitedError) is the backstop if a cancel races a resume.
+    if (runIdsToCancel.length > 0) {
+      try {
+        await hatchet.runs.cancel({ ids: runIdsToCancel });
+      } catch (err) {
+        logger.warn("Failed to cancel exited journey runs", {
+          count: runIdsToCancel.length,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
   }
 
   return results;

package/src/lib/mailer.ts

@@ -1,3 +1,10 @@
+import type {
+  BatchEmailItem,
+  EmailProvider,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/core";
 import type { Database } from "@hogsend/db";
 import { emailPreferences, emailSends } from "@hogsend/db";
 import type {
@@ -6,13 +13,6 @@ import type {
   TemplateName,
 } from "@hogsend/email";
 import { getTemplate, renderToHtml, renderToPlainText } from "@hogsend/email";
-import type {
-  BatchEmailItem,
-  EmailProvider,
-  WebhookEvent,
-  WebhookEventType,
-  WebhookHandlerMap,
-} from "@hogsend/plugin-resend";
 import { eq, sql } from "drizzle-orm";
 import type {
   EmailService,
@@ -20,7 +20,7 @@ import type {
   EmailServiceSendOptions,
   EmailServiceWebhookOptions,
   EmailServiceWebhookResult,
-  SendEmailOptions,
+  SendRawOptions,
   SendResult,
   TrackedSendResult,
 } from "./email-service-types.js";
@@ -125,7 +125,7 @@ export function createTrackedMailer(
       };
     },
 
-    async sendRaw(options: SendEmailOptions): Promise<SendResult> {
+    async sendRaw(options: SendRawOptions): Promise<SendResult> {
       return provider.send({ ...options, from: resolveFrom(options.from) });
     },
 

package/src/lib/notifications.ts

@@ -1,3 +1,5 @@
+import { getEmailService } from "./email.js";
+
 export async function sendWebhook(
   url: string,
   payload: Record<string, unknown>,
@@ -32,25 +34,22 @@ export async function sendSlackNotification(
   return sendWebhook(webhookUrl, { text });
 }
 
-import { createResendClient } from "@hogsend/plugin-resend";
-
 export async function sendEmailNotification(opts: {
   to: string;
   subject: string;
   body: string;
-  resendApiKey: string;
 }): Promise<{ ok: boolean; error?: string }> {
   try {
-    const client = createResendClient({ apiKey: opts.resendApiKey });
-    const { error } = await client.emails.send({
+    // Route through the injected EmailProvider (via the mailer's `sendRaw`)
+    // instead of constructing a raw Resend client from process.env. The
+    // alerting task runs under the worker, where createHogsendClient has already
+    // installed the email service.
+    await getEmailService().sendRaw({
       from: "Hogsend Alerts <alerts@hogsend.com>",
       to: opts.to,
       subject: opts.subject,
       html: opts.body,
     });
-    if (error) {
-      return { ok: false, error: error.message };
-    }
     return { ok: true };
   } catch (err) {
     return {

package/src/lib/posthog.ts

@@ -1,7 +1,5 @@
-import {
-  createPostHogService,
-  type PostHogService,
-} from "@hogsend/plugin-posthog";
+import type { PostHogService } from "@hogsend/core";
+import { createPostHogService } from "@hogsend/plugin-posthog";
 import { getRedis } from "./redis.js";
 
 let _posthog: PostHogService | undefined;

package/src/lib/singleton.ts

@@ -0,0 +1,56 @@
+/**
+ * Tiny process-singletons: a value set once by `createHogsendClient` at startup
+ * and read by module-level task-execution sites that have no client reference of
+ * their own (journey/bucket durable tasks, the send-email task). Replaces the
+ * hand-rolled `let _x` + set/get/reset trios that were copied across the engine.
+ *
+ * Two variants:
+ * - `createSingleton` — required: `get()` throws if read before it is set.
+ * - `createOptionalSingleton` — `undefined` is a legitimate value (e.g. analytics
+ *   with no `POSTHOG_API_KEY`); `get()` returns `T | undefined` and never throws.
+ */
+
+export interface Singleton<T> {
+  set(value: T): void;
+  get(): T;
+  reset(): void;
+}
+
+export interface OptionalSingleton<T> {
+  set(value: T | undefined): void;
+  get(): T | undefined;
+  reset(): void;
+}
+
+export function createSingleton<T>(name: string): Singleton<T> {
+  let value: T | undefined;
+  return {
+    set(next: T): void {
+      value = next;
+    },
+    get(): T {
+      if (value === undefined) {
+        throw new Error(`${name} not initialized. Call its setter at startup.`);
+      }
+      return value;
+    },
+    reset(): void {
+      value = undefined;
+    },
+  };
+}
+
+export function createOptionalSingleton<T>(): OptionalSingleton<T> {
+  let value: T | undefined;
+  return {
+    set(next: T | undefined): void {
+      value = next;
+    },
+    get(): T | undefined {
+      return value;
+    },
+    reset(): void {
+      value = undefined;
+    },
+  };
+}

package/src/lib/tracked.ts

@@ -1,3 +1,4 @@
+import type { EmailProvider } from "@hogsend/core";
 import type { Database } from "@hogsend/db";
 import { emailPreferences, emailSends } from "@hogsend/db";
 import type {
@@ -7,7 +8,6 @@ import type {
   TemplateRegistry,
 } from "@hogsend/email";
 import { getTemplate, renderToHtml } from "@hogsend/email";
-import type { EmailProvider } from "@hogsend/plugin-resend";
 import { eq } from "drizzle-orm";
 import type {
   FrequencyCapConfig,

package/src/lib/tracking-events.ts

@@ -1,7 +1,7 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { PostHogService } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
-import type { PostHogService } from "@hogsend/plugin-posthog";
 import { eq } from "drizzle-orm";
 import { ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";

package/src/lib/worker-heartbeat.ts

@@ -0,0 +1,78 @@
+import type { Logger } from "./logger.js";
+import { getRedis } from "./redis.js";
+
+/**
+ * Worker liveness heartbeat. The worker and API are separate processes, so the
+ * API (and the Studio, via `GET /v1/health`) cannot otherwise tell whether a
+ * worker is actually connected — which is exactly the "journeys silently don't
+ * fire because the worker isn't running" footgun. The worker writes a TTL'd key
+ * to Redis on an interval; readers treat its presence as "a worker is alive".
+ *
+ * Redis is the channel because the health route already probes Redis and both
+ * processes can reach it — no direct process-to-process coupling, no migration.
+ * Everything here is best-effort: a missing/unreachable Redis never crashes the
+ * worker and simply reads back as "down".
+ */
+const HEARTBEAT_KEY = "hogsend:worker:heartbeat";
+const TTL_SECONDS = 30;
+const REFRESH_MS = 10_000;
+
+export interface WorkerHeartbeat {
+  /** True when a fresh worker heartbeat is present in Redis. */
+  alive: boolean;
+  /** ISO timestamp the worker last wrote, when alive. */
+  lastSeenAt?: string;
+}
+
+/**
+ * Begin writing the worker heartbeat. Writes once immediately, then refreshes
+ * every {@link REFRESH_MS} with a {@link TTL_SECONDS} expiry — so an ungraceful
+ * worker death is reflected as "down" within the TTL. Returns a stop function
+ * that clears the timer and deletes the key for an immediate "down" signal on
+ * graceful shutdown.
+ */
+export function startWorkerHeartbeat(logger: Logger): () => Promise<void> {
+  let warned = false;
+  const write = async () => {
+    try {
+      await getRedis().set(
+        HEARTBEAT_KEY,
+        new Date().toISOString(),
+        "EX",
+        TTL_SECONDS,
+      );
+    } catch (err) {
+      // Log the first failure only — a Redis-less deploy would otherwise spam.
+      if (!warned) {
+        warned = true;
+        logger.debug("Worker heartbeat write failed (Redis unreachable?)", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  void write();
+  const timer = setInterval(() => void write(), REFRESH_MS);
+  // Never hold the process open for the heartbeat alone.
+  timer.unref?.();
+
+  return async () => {
+    clearInterval(timer);
+    try {
+      await getRedis().del(HEARTBEAT_KEY);
+    } catch {
+      // Best-effort — the TTL expires it anyway.
+    }
+  };
+}
+
+/** Read the current worker heartbeat. Resolves to `{ alive: false }` if Redis is unreachable. */
+export async function getWorkerHeartbeat(): Promise<WorkerHeartbeat> {
+  try {
+    const lastSeenAt = await getRedis().get(HEARTBEAT_KEY);
+    return lastSeenAt ? { alive: true, lastSeenAt } : { alive: false };
+  } catch {
+    return { alive: false };
+  }
+}

package/src/routes/health.ts

@@ -4,12 +4,21 @@ import { sql } from "drizzle-orm";
 import type { AppEnv } from "../app.js";
 import { API_VERSION } from "../env.js";
 import { getRedis } from "../lib/redis.js";
+import { getWorkerHeartbeat } from "../lib/worker-heartbeat.js";
 
 const componentSchema = z.object({
   status: z.enum(["up", "down"]),
   latencyMs: z.number().optional(),
 });
 
+// Worker connectivity, derived from the Redis heartbeat. Informational only —
+// the worker is a separate service, so its absence does NOT make the API
+// "degraded" (that would falsely fail the API's own healthcheck).
+const workerComponentSchema = z.object({
+  status: z.enum(["up", "down"]),
+  lastSeenAt: z.string().optional(),
+});
+
 // Per-track schema version block. Two tracks: `engine` (bundled @hogsend/db
 // migrations) and `client` (the client repo's own migrations). See
 // docs/UPGRADING.md "Two-track migrations".
@@ -28,6 +37,7 @@ const healthResponseSchema = z.object({
   components: z.object({
     database: componentSchema,
     redis: componentSchema,
+    worker: workerComponentSchema,
   }),
   schema: z.object({
     engine: trackSchema,
@@ -73,7 +83,7 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
   async (c) => {
     const { db, clientJournal } = c.get("container");
 
-    const [dbCheck, redisCheck, engine, client] = await Promise.all([
+    const [dbCheck, redisCheck, heartbeat, engine, client] = await Promise.all([
       checkComponent(async () => {
         await db.execute(sql`SELECT 1`);
       }),
@@ -86,6 +96,7 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
         // host is genuinely unreachable → a truthful "down").
         await getRedis().ping();
       }),
+      getWorkerHeartbeat(),
       getEngineSchemaVersion(db),
       getClientSchemaVersion(db, clientJournal ?? { entries: [] }),
     ]);
@@ -123,6 +134,10 @@ export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
         components: {
           database: dbCheck,
           redis: redisCheck,
+          worker: {
+            status: heartbeat.alive ? ("up" as const) : ("down" as const),
+            lastSeenAt: heartbeat.lastSeenAt,
+          },
         },
       },
       200,