@hogsend/engine 0.38.2 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,8 +10,24 @@
10
10
  * categories (`transactional`, `journey`) and rejected here (open risk #11).
11
11
  */
12
12
 
13
- /** A list id can collide with these built-in non-list categories — reject. */
14
- const RESERVED_LIST_IDS = new Set(["transactional", "journey"]);
13
+ /**
14
+ * List ids that collide with the engine's built-in, non-list
15
+ * `email_preferences.categories` keys — rejected by {@link defineList}, and
16
+ * ALSO the allowlist of categories a template may legitimately carry that are
17
+ * NOT a defined list (the boot-time template-category guard in `container.ts`
18
+ * reuses this set so the two can never drift). Exported for that reuse.
19
+ */
20
+ export const RESERVED_LIST_IDS = new Set(["transactional", "journey"]);
21
+
22
+ /**
23
+ * Is `id` one of the reserved built-in categories ({@link RESERVED_LIST_IDS})?
24
+ * Case-insensitive, matching the `defineList` reservation check — so callers
25
+ * (e.g. the container's template-category validation) never re-implement the
26
+ * comparison and can't drift from the reservation rule.
27
+ */
28
+ export function isReservedListId(id: string): boolean {
29
+ return RESERVED_LIST_IDS.has(id.toLowerCase());
30
+ }
15
31
 
16
32
  /** Allowed list-id shape: alphanumerics, dash, underscore (case-insensitive). */
17
33
  const LIST_ID_PATTERN = /^[a-z0-9_-]+$/i;
@@ -60,7 +76,7 @@ export function defineList<const Id extends string>(meta: {
60
76
  );
61
77
  }
62
78
 
63
- if (RESERVED_LIST_IDS.has(id.toLowerCase())) {
79
+ if (isReservedListId(id)) {
64
80
  throw new Error(
65
81
  `Reserved list id "${id}": "transactional" and "journey" are built-in email-preference categories and cannot be used as list ids.`,
66
82
  );
@@ -0,0 +1,165 @@
1
+ /**
2
+ * Admin-plane campaigns routes for Studio (session-cookie auth via the parent
3
+ * adminRouter's `requireAdmin`; Studio cannot use the hsk_-keyed data-plane
4
+ * routes). Observe + cancel only — campaigns are AUTHORED in code
5
+ * (`defineCampaign()`) or via the data-plane `POST /v1/campaigns`, never from
6
+ * Studio. The list/get/cancel semantics mirror `routes/campaigns/index.ts`
7
+ * exactly (same serializer, same cancel CAS).
8
+ */
9
+ import { campaigns } from "@hogsend/db";
10
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
11
+ import { and, desc, eq, inArray } from "drizzle-orm";
12
+ import type { AppEnv } from "../../app.js";
13
+ import { errorSchema } from "../../lib/schemas.js";
14
+ import { campaignSchema, serializeCampaign } from "../campaigns/index.js";
15
+
16
+ const listRouteDef = createRoute({
17
+ method: "get",
18
+ path: "/",
19
+ tags: ["Admin"],
20
+ summary: "List campaigns (Studio)",
21
+ request: {
22
+ query: z.object({
23
+ status: z.string().optional(),
24
+ limit: z.coerce.number().int().min(1).max(200).default(50),
25
+ offset: z.coerce.number().int().min(0).default(0),
26
+ }),
27
+ },
28
+ responses: {
29
+ 200: {
30
+ content: {
31
+ "application/json": {
32
+ schema: z.object({
33
+ campaigns: z.array(campaignSchema),
34
+ hasMore: z.boolean(),
35
+ }),
36
+ },
37
+ },
38
+ description: "Campaigns, newest first",
39
+ },
40
+ },
41
+ });
42
+
43
+ const getRouteDef = createRoute({
44
+ method: "get",
45
+ path: "/{id}",
46
+ tags: ["Admin"],
47
+ summary: "Get a campaign (Studio)",
48
+ request: {
49
+ params: z.object({ id: z.string() }),
50
+ },
51
+ responses: {
52
+ 200: {
53
+ content: { "application/json": { schema: campaignSchema } },
54
+ description: "The campaign",
55
+ },
56
+ 404: {
57
+ content: { "application/json": { schema: errorSchema } },
58
+ description: "Unknown campaign id",
59
+ },
60
+ },
61
+ });
62
+
63
+ const cancelRouteDef = createRoute({
64
+ method: "post",
65
+ path: "/{id}/cancel",
66
+ tags: ["Admin"],
67
+ summary: "Cancel a campaign (Studio)",
68
+ request: {
69
+ params: z.object({ id: z.string() }),
70
+ },
71
+ responses: {
72
+ 200: {
73
+ content: { "application/json": { schema: campaignSchema } },
74
+ description: "The canceled campaign",
75
+ },
76
+ 404: {
77
+ content: { "application/json": { schema: errorSchema } },
78
+ description: "Unknown campaign id",
79
+ },
80
+ 409: {
81
+ content: { "application/json": { schema: errorSchema } },
82
+ description: "Campaign is in a terminal state and cannot be canceled",
83
+ },
84
+ },
85
+ });
86
+
87
+ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
88
+ .openapi(listRouteDef, async (c) => {
89
+ const { db } = c.get("container");
90
+ const { status, limit, offset } = c.req.valid("query");
91
+
92
+ const statuses = status
93
+ ?.split(",")
94
+ .map((s) => s.trim())
95
+ .filter(Boolean);
96
+
97
+ const rows = await db
98
+ .select()
99
+ .from(campaigns)
100
+ .where(
101
+ statuses && statuses.length > 0
102
+ ? inArray(campaigns.status, statuses)
103
+ : undefined,
104
+ )
105
+ .orderBy(desc(campaigns.createdAt))
106
+ .limit(limit + 1)
107
+ .offset(offset);
108
+
109
+ return c.json(
110
+ {
111
+ campaigns: rows.slice(0, limit).map(serializeCampaign),
112
+ hasMore: rows.length > limit,
113
+ },
114
+ 200,
115
+ );
116
+ })
117
+ .openapi(getRouteDef, async (c) => {
118
+ const { db } = c.get("container");
119
+ const { id } = c.req.valid("param");
120
+
121
+ const rows = await db
122
+ .select()
123
+ .from(campaigns)
124
+ .where(eq(campaigns.id, id))
125
+ .limit(1);
126
+ if (!rows[0]) {
127
+ return c.json({ error: `Unknown campaign: ${id}` }, 404);
128
+ }
129
+ return c.json(serializeCampaign(rows[0]), 200);
130
+ })
131
+ .openapi(cancelRouteDef, async (c) => {
132
+ const { db } = c.get("container");
133
+ const { id } = c.req.valid("param");
134
+
135
+ const canceled = await db
136
+ .update(campaigns)
137
+ .set({
138
+ status: "canceled",
139
+ canceledAt: new Date(),
140
+ updatedAt: new Date(),
141
+ })
142
+ .where(
143
+ and(
144
+ eq(campaigns.id, id),
145
+ inArray(campaigns.status, ["scheduled", "queued", "sending"]),
146
+ ),
147
+ )
148
+ .returning();
149
+ if (canceled[0]) {
150
+ return c.json(serializeCampaign(canceled[0]), 200);
151
+ }
152
+
153
+ const existing = await db
154
+ .select()
155
+ .from(campaigns)
156
+ .where(eq(campaigns.id, id))
157
+ .limit(1);
158
+ if (!existing[0]) {
159
+ return c.json({ error: `Unknown campaign: ${id}` }, 404);
160
+ }
161
+ return c.json(
162
+ { error: `Campaign is ${existing[0].status} and cannot be canceled` },
163
+ 409,
164
+ );
165
+ });
@@ -10,6 +10,7 @@ import { apiKeysRouter } from "./api-keys.js";
10
10
  import { auditLogsRouter } from "./audit-logs.js";
11
11
  import { bucketsRouter } from "./buckets.js";
12
12
  import { bulkRouter } from "./bulk.js";
13
+ import { adminCampaignsRouter } from "./campaigns.js";
13
14
  import { adminConnectorsRouter } from "./connectors.js";
14
15
  import { contactsRouter } from "./contacts.js";
15
16
  import { dlqRouter } from "./dlq.js";
@@ -20,6 +21,7 @@ import { journeyLogsRouter } from "./journey-logs.js";
20
21
  import { journeysRouter } from "./journeys.js";
21
22
  import { linksRouter } from "./links.js";
22
23
  import { metricsRouter } from "./metrics.js";
24
+ import { openEditorRouter } from "./open-editor.js";
23
25
  import { preferencesRouter } from "./preferences.js";
24
26
  import { providerCredentialsRouter } from "./provider-credentials.js";
25
27
  import { readinessRouter } from "./readiness.js";
@@ -38,7 +40,9 @@ adminRouter.route("/contacts", contactsRouter);
38
40
  adminRouter.route("/contacts", preferencesRouter);
39
41
  adminRouter.route("/contacts", timelineRouter);
40
42
  adminRouter.route("/journeys", journeysRouter);
43
+ adminRouter.route("/open-in-editor", openEditorRouter);
41
44
  adminRouter.route("/buckets", bucketsRouter);
45
+ adminRouter.route("/campaigns", adminCampaignsRouter);
42
46
  adminRouter.route("/events", eventsRouter);
43
47
  adminRouter.route("/emails", emailsRouter);
44
48
  adminRouter.route("/links", linksRouter);
@@ -1,3 +1,4 @@
1
+ import { type JourneyGraph, journeyGraphSchema } from "@hogsend/core";
1
2
  import {
2
3
  type Database,
3
4
  emailSends,
@@ -5,6 +6,7 @@ import {
5
6
  journeyLogs,
6
7
  journeyStates,
7
8
  } from "@hogsend/db";
9
+ import { getTemplateNames } from "@hogsend/email";
8
10
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
9
11
  import {
10
12
  and,
@@ -17,8 +19,16 @@ import {
17
19
  sql,
18
20
  } from "drizzle-orm";
19
21
  import type { AppEnv } from "../../app.js";
22
+ import { buildJourneyGraph } from "../../journeys/graph/build-graph.js";
20
23
  import { ingestEvent } from "../../lib/ingestion.js";
21
24
 
25
+ /**
26
+ * Per-process cache of the built {@link JourneyGraph}. A journey's `runSource`
27
+ * (and its `meta`) is static for the life of the process, so the AST extraction
28
+ * only needs to run once per journey id. Keyed by journey id.
29
+ */
30
+ const journeyGraphCache = new Map<string, JourneyGraph>();
31
+
22
32
  const journeySchema = z.object({
23
33
  id: z.string(),
24
34
  name: z.string(),
@@ -403,6 +413,57 @@ const templatesRoute = createRoute({
403
413
  },
404
414
  });
405
415
 
416
+ const graphRoute = createRoute({
417
+ method: "get",
418
+ path: "/{id}/graph",
419
+ tags: ["Admin — Journeys"],
420
+ summary: "Journey visual workflow graph with per-node live/failed metrics",
421
+ request: {
422
+ params: z.object({ id: z.string() }),
423
+ },
424
+ responses: {
425
+ 200: {
426
+ content: {
427
+ "application/json": {
428
+ schema: z.object({
429
+ graph: journeyGraphSchema,
430
+ metrics: z.object({
431
+ enrolled: z.number(),
432
+ terminals: z.object({
433
+ completed: z.number(),
434
+ failed: z.number(),
435
+ exited: z.number(),
436
+ }),
437
+ // Keyed by graph node id. `live` = people currently sitting at
438
+ // that node (status active/waiting), `failed` = instances whose
439
+ // last durable node was this one when they failed. `templateKey`
440
+ // is the resolved email template key for `send` nodes (for the
441
+ // Studio side-panel preview) — present only when resolvable.
442
+ // `templatePath` is that template component's source file (for the
443
+ // Studio "open in editor" affordance) — present only in dev where
444
+ // the registry carries source paths.
445
+ nodes: z.record(
446
+ z.string(),
447
+ z.object({
448
+ live: z.number(),
449
+ failed: z.number(),
450
+ templateKey: z.string().optional(),
451
+ templatePath: z.string().optional(),
452
+ }),
453
+ ),
454
+ }),
455
+ }),
456
+ },
457
+ },
458
+ description: "Journey graph (IR) plus retroactive per-node metrics",
459
+ },
460
+ 404: {
461
+ content: { "application/json": { schema: errorSchema } },
462
+ description: "Journey not found",
463
+ },
464
+ },
465
+ });
466
+
406
467
  export const journeysRouter = new OpenAPIHono<AppEnv>()
407
468
  .openapi(listRoute, async (c) => {
408
469
  const { db, registry } = c.get("container");
@@ -770,4 +831,221 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
770
831
  },
771
832
  200,
772
833
  );
834
+ })
835
+ .openapi(graphRoute, async (c) => {
836
+ const { db, registry, journeySources, journeySourceLocations, templates } =
837
+ c.get("container");
838
+ const { id } = c.req.valid("param");
839
+
840
+ const meta = registry.get(id);
841
+ if (!meta) {
842
+ return c.json({ error: "Journey not found" }, 404);
843
+ }
844
+
845
+ // Build (and cache) the IR — runSource is static per process, so a repeat
846
+ // request re-uses the parse rather than re-walking the AST. The captured
847
+ // call-site (also static per process) is baked into the cached graph.
848
+ let graph = journeyGraphCache.get(id);
849
+ if (!graph) {
850
+ graph = buildJourneyGraph({ runSource: journeySources.get(id), meta });
851
+ const source = journeySourceLocations.get(id);
852
+ if (source) graph.source = source;
853
+ journeyGraphCache.set(id, graph);
854
+ }
855
+
856
+ // One grouped query gives us BOTH per-node live/failed AND the status
857
+ // totals for enrolled + terminals (sum across all node ids per status).
858
+ const perNode = await db
859
+ .select({
860
+ nodeId: journeyStates.currentNodeId,
861
+ status: journeyStates.status,
862
+ count: count(),
863
+ })
864
+ .from(journeyStates)
865
+ .where(
866
+ and(eq(journeyStates.journeyId, id), isNull(journeyStates.deletedAt)),
867
+ )
868
+ .groupBy(journeyStates.currentNodeId, journeyStates.status);
869
+
870
+ // Default every graph node to zero, then overlay the observed counts. Only
871
+ // start/sleep/wait/checkpoint node ids ever appear as `current_node_id`;
872
+ // instantaneous nodes (send/trigger/capture/connector) correctly stay 0.
873
+ const nodeMetrics: Record<
874
+ string,
875
+ {
876
+ live: number;
877
+ failed: number;
878
+ templateKey?: string;
879
+ templatePath?: string;
880
+ }
881
+ > = {};
882
+ for (const node of graph.nodes) {
883
+ nodeMetrics[node.id] = { live: 0, failed: 0 };
884
+ }
885
+
886
+ const statusTotals: Record<string, number> = {};
887
+ for (const row of perNode) {
888
+ const n = Number(row.count);
889
+ statusTotals[row.status] = (statusTotals[row.status] ?? 0) + n;
890
+ const nodeId = row.nodeId;
891
+ if (!nodeId) continue;
892
+ const entry = nodeMetrics[nodeId] ?? { live: 0, failed: 0 };
893
+ if (row.status === "active" || row.status === "waiting") {
894
+ entry.live += n;
895
+ } else if (row.status === "failed") {
896
+ entry.failed += n;
897
+ }
898
+ nodeMetrics[nodeId] = entry;
899
+ }
900
+
901
+ const enrolled = Object.values(statusTotals).reduce((a, b) => a + b, 0);
902
+
903
+ // Resolve a real email template key per `send` node for the Studio
904
+ // side-panel preview. The preview only needs the registry key (it renders
905
+ // the React Email component — no send data), so STATIC resolution is the
906
+ // primary mechanism and a never-sent journey still previews. Priority:
907
+ // (1) literal `meta.template` — already the registry key.
908
+ // (2) STATIC exact: the node's `subtitle` is the Templates const name for
909
+ // member-expr sends (`FEEDBACK_NPS_SURVEY`); lowercase + `_`→`-`
910
+ // (`feedback-nps-survey`) and use it IFF that key is in the registry.
911
+ // (2b) STATIC prefix: else the single LONGEST registry key that is a
912
+ // segment-prefix of the kebab'd const name (`activation-nudge-series`
913
+ // → `activation-nudge`). Only when that longest prefix is unique — a
914
+ // wrong preview is worse than none, so an ambiguous tie stays unresolved.
915
+ // (3) journey_logs rows (action='send') whose `to_node_id` is this send
916
+ // node's site id (`send:<site>`), reading `detail.template` — site-
917
+ // keyed, so two sends of one template on different branches stay
918
+ // distinct.
919
+ // (4) observed email_sends template keys (join via journeyStateId) mapped
920
+ // onto still-unresolved send nodes in source order.
921
+ // The resolved key rides on `metrics.nodes[id].templateKey` (NOT the cached
922
+ // graph, which stays immutable + DB-independent).
923
+ const sendNodes = graph.nodes.filter((node) => node.type === "send");
924
+ if (sendNodes.length > 0) {
925
+ const sendIds = new Set(sendNodes.map((node) => node.id));
926
+ const setTemplate = (nodeId: string, key: string) => {
927
+ const entry = nodeMetrics[nodeId] ?? { live: 0, failed: 0 };
928
+ if (!entry.templateKey) {
929
+ entry.templateKey = key;
930
+ // Best-effort source path (dev-only; see `withSources`) for the
931
+ // Studio "open template in editor" affordance.
932
+ const def = (templates as Record<string, { sourcePath?: string }>)[
933
+ key
934
+ ];
935
+ if (def?.sourcePath) entry.templatePath = def.sourcePath;
936
+ }
937
+ nodeMetrics[nodeId] = entry;
938
+ };
939
+
940
+ // (1) literal templates already carry the real key in the IR.
941
+ for (const node of sendNodes) {
942
+ if (node.meta?.template) setTemplate(node.id, node.meta.template);
943
+ }
944
+
945
+ // (2/2b) static const-name → registry key (no runtime data needed):
946
+ // exact kebab match, else the unique longest segment-prefix key.
947
+ const registryKeys = getTemplateNames(templates) as string[];
948
+ const registeredKeys = new Set<string>(registryKeys);
949
+ const resolveStatic = (constName: string): string | undefined => {
950
+ const kebab = constName.toLowerCase().replace(/_/g, "-");
951
+ if (registeredKeys.has(kebab)) return kebab;
952
+ // Longest registry key that is a segment-prefix of the kebab'd name.
953
+ let best: string | undefined;
954
+ let bestLen = -1;
955
+ let ambiguous = false;
956
+ for (const key of registryKeys) {
957
+ if (!kebab.startsWith(`${key}-`)) continue;
958
+ if (key.length > bestLen) {
959
+ best = key;
960
+ bestLen = key.length;
961
+ ambiguous = false;
962
+ } else if (key.length === bestLen) {
963
+ ambiguous = true;
964
+ }
965
+ }
966
+ return ambiguous ? undefined : best;
967
+ };
968
+ for (const node of sendNodes) {
969
+ if (nodeMetrics[node.id]?.templateKey || !node.subtitle) continue;
970
+ const key = resolveStatic(node.subtitle);
971
+ if (key) setTemplate(node.id, key);
972
+ }
973
+
974
+ // (3) journey_logs site-join (only if something is still unresolved).
975
+ if (sendNodes.some((node) => !nodeMetrics[node.id]?.templateKey)) {
976
+ const logRows = await db
977
+ .select({
978
+ toNodeId: journeyLogs.toNodeId,
979
+ template: sql<string | null>`${journeyLogs.detail} ->> 'template'`,
980
+ })
981
+ .from(journeyLogs)
982
+ .innerJoin(
983
+ journeyStates,
984
+ eq(journeyLogs.journeyStateId, journeyStates.id),
985
+ )
986
+ .where(
987
+ and(
988
+ eq(journeyStates.journeyId, id),
989
+ isNull(journeyStates.deletedAt),
990
+ eq(journeyLogs.action, "send"),
991
+ ),
992
+ );
993
+ for (const row of logRows) {
994
+ const nodeId = row.toNodeId;
995
+ if (!nodeId || !row.template || !sendIds.has(nodeId)) continue;
996
+ setTemplate(nodeId, row.template);
997
+ }
998
+ }
999
+
1000
+ // (4) email_sends fallback, mapped in source order.
1001
+ const unresolved = sendNodes.filter(
1002
+ (node) => !nodeMetrics[node.id]?.templateKey,
1003
+ );
1004
+ if (unresolved.length > 0) {
1005
+ const observedRows = await db
1006
+ .select({
1007
+ templateKey: emailSends.templateKey,
1008
+ firstSeen: sql<string | null>`min(${emailSends.createdAt})`,
1009
+ })
1010
+ .from(emailSends)
1011
+ .innerJoin(
1012
+ journeyStates,
1013
+ eq(emailSends.journeyStateId, journeyStates.id),
1014
+ )
1015
+ .where(
1016
+ and(
1017
+ eq(journeyStates.journeyId, id),
1018
+ isNull(journeyStates.deletedAt),
1019
+ isNotNull(emailSends.templateKey),
1020
+ ),
1021
+ )
1022
+ .groupBy(emailSends.templateKey);
1023
+ const observed = observedRows
1024
+ .filter((r): r is { templateKey: string; firstSeen: string | null } =>
1025
+ Boolean(r.templateKey),
1026
+ )
1027
+ .sort((a, b) => (a.firstSeen ?? "").localeCompare(b.firstSeen ?? ""))
1028
+ .map((r) => r.templateKey);
1029
+ unresolved.forEach((node, i) => {
1030
+ const key = observed[i];
1031
+ if (key) setTemplate(node.id, key);
1032
+ });
1033
+ }
1034
+ }
1035
+
1036
+ return c.json(
1037
+ {
1038
+ graph,
1039
+ metrics: {
1040
+ enrolled,
1041
+ terminals: {
1042
+ completed: statusTotals.completed ?? 0,
1043
+ failed: statusTotals.failed ?? 0,
1044
+ exited: statusTotals.exited ?? 0,
1045
+ },
1046
+ nodes: nodeMetrics,
1047
+ },
1048
+ },
1049
+ 200,
1050
+ );
773
1051
  });
@@ -0,0 +1,106 @@
1
+ import { existsSync } from "node:fs";
2
+ import { createRequire } from "node:module";
3
+ import { OpenAPIHono } from "@hono/zod-openapi";
4
+ import { z } from "zod";
5
+ import type { AppEnv } from "../../app.js";
6
+ import { createLogger } from "../../lib/logger.js";
7
+
8
+ /**
9
+ * Dev-only "open in editor" endpoint. The Studio SPA can't spawn a process, so
10
+ * it POSTs a source path here and the engine — running on the SAME machine as
11
+ * the developer in local dev — opens it in whatever editor they use.
12
+ *
13
+ * Editor AUTO-DETECTION is delegated to `launch-editor` (the mechanism behind
14
+ * Vite/CRA error overlays): it honours `$LAUNCH_EDITOR`/`$VISUAL`/`$EDITOR`,
15
+ * else scans running processes for a known editor (Cursor, VS Code, Windsurf,
16
+ * WebStorm, …). So there is no editor picker — it just opens "your editor".
17
+ *
18
+ * Safety envelope (this spawns a process on the host):
19
+ * - DEV ONLY: hard 404 when NODE_ENV=production.
20
+ * - Admin-authed: mounted under the admin router (requireAdmin).
21
+ * - Path allowlist: absolute path, a known source extension, and it must exist.
22
+ * - `launch-editor` spawns argv (never a shell string), so a crafted path can't
23
+ * inject a command.
24
+ */
25
+
26
+ const require = createRequire(import.meta.url);
27
+
28
+ // launch-editor is CommonJS and ships no types. Signature:
29
+ // launch(file, [specifiedEditor], [onErrorCallback]) — no editor => auto-guess.
30
+ type LaunchEditor = (
31
+ file: string,
32
+ editor?: string,
33
+ onError?: (fileName: string, errorMsg: string) => void,
34
+ ) => void;
35
+
36
+ // Loaded LAZILY, only on the dev-only code path below, so a production build
37
+ // never `require`s it — keeps launch-editor out of the prod dependency graph
38
+ // (and away from the CJS-in-ESM bundling gotcha for npm consumers).
39
+ let launchEditor: LaunchEditor | undefined;
40
+ function getLaunchEditor(): LaunchEditor {
41
+ if (!launchEditor) {
42
+ launchEditor = require("launch-editor") as LaunchEditor;
43
+ }
44
+ return launchEditor;
45
+ }
46
+
47
+ const logger = createLogger(process.env.LOG_LEVEL);
48
+
49
+ const bodySchema = z.object({
50
+ path: z.string().min(1),
51
+ line: z.number().int().positive().optional(),
52
+ });
53
+
54
+ /** Source files the Studio can deep-link (journeys + email templates + kin). */
55
+ const SOURCE_EXT = /\.(tsx?|jsx?|mjs|cjs)$/;
56
+
57
+ /**
58
+ * Editor to spawn when none is running and no `$HS_EDITOR`/`$VISUAL`/`$EDITOR`
59
+ * is set. `cursor`/`code`/`windsurf` all accept the `file:line` target.
60
+ */
61
+ const DEFAULT_EDITOR = "cursor";
62
+
63
+ export const openEditorRouter = new OpenAPIHono<AppEnv>().post(
64
+ "/",
65
+ async (c) => {
66
+ if (process.env.NODE_ENV === "production") {
67
+ return c.json({ error: "not available" }, 404);
68
+ }
69
+
70
+ let body: z.infer<typeof bodySchema>;
71
+ try {
72
+ body = bodySchema.parse(await c.req.json());
73
+ } catch {
74
+ return c.json({ error: "invalid body" }, 400);
75
+ }
76
+
77
+ const { path, line } = body;
78
+ if (!path.startsWith("/") || !SOURCE_EXT.test(path)) {
79
+ return c.json({ error: "path not allowed" }, 403);
80
+ }
81
+ if (!existsSync(path)) {
82
+ return c.json({ error: "file not found" }, 404);
83
+ }
84
+
85
+ const target = line ? `${path}:${line}` : path;
86
+ const launch = getLaunchEditor();
87
+ const onErr = (fileName: string, errorMsg: string) => {
88
+ logger.warn(`open-in-editor failed for ${fileName}: ${errorMsg}`);
89
+ };
90
+
91
+ // `launch-editor` auto-detects a RUNNING editor (or $VISUAL/$EDITOR), but
92
+ // launches nothing when the editor is closed and no env var is set. So:
93
+ // 1. `HS_EDITOR` (explicit override) → spawn it directly, open or not.
94
+ // 2. else auto-detect a running editor.
95
+ // 3. if that finds nothing, fall back to a default editor and spawn it —
96
+ // this is what makes "open in IDE" work even when it isn't running yet.
97
+ const forced = process.env.HS_EDITOR?.trim();
98
+ if (forced) {
99
+ launch(target, forced, onErr);
100
+ } else {
101
+ launch(target, undefined, () => launch(target, DEFAULT_EDITOR, onErr));
102
+ }
103
+
104
+ return c.json({ ok: true, target }, 200);
105
+ },
106
+ );