@agent-native/core 0.138.0 → 0.140.0

package/corpus/templates/plan/server/lib/comment-notifications.ts

@@ -14,6 +14,8 @@ import {
 import type { PlanBundle, PlanComment } from "../../shared/types.js";
 import { getDb, schema } from "../db/index.js";
 
+export const PLAN_COMMENT_EMAIL_ID = "plan.plan-comment";
+
 type CommentNotificationInput = {
   bundle: PlanBundle;
   insertedCommentIds: string[];
@@ -205,40 +207,64 @@ export function planCommentNotificationRecipients(input: {
   return Array.from(recipients.values());
 }
 
-async function sendPlanCommentNotification(input: {
-  recipient: NotificationRecipient;
-  comment: PlanComment;
+export function renderPlanCommentEmail(input: {
+  actor: string;
+  app: string;
   planTitle: string;
-  planId: string;
+  planUrl: string;
+  message: string;
+  isReply: boolean;
+  reason: NotificationRecipient["reason"];
 }) {
-  const actor = actorName(input.comment);
-  const app = appName();
-  const isReply = Boolean(input.comment.parentCommentId);
-  const subject = isReply
-    ? `${actor} replied to a comment on "${input.planTitle}"`
-    : `${actor} commented on "${input.planTitle}"`;
   const actionText =
-    input.recipient.reason === "mention"
+    input.reason === "mention"
       ? "mentioned you in a comment on"
-      : input.recipient.reason === "plan-owner"
+      : input.reason === "plan-owner"
         ? "left a comment on your plan"
         : "replied in a comment thread you participated in";
-  const { html, text } = renderEmail({
-    preheader: `${actor} ${actionText} on ${app}.`,
-    heading: isReply ? "New reply on your plan" : "New comment on your plan",
-    paragraphs: [
-      `${emailStrong(actor)} ${actionText} ${emailStrong(input.planTitle)}.`,
-      `Comment: "${commentExcerpt(input.comment.message)}"`,
-    ],
-    cta: { label: "Open plan", url: planUrl(input.planId) },
-    footer:
-      input.recipient.reason === "plan-owner"
-        ? "You received this because you own this plan."
-        : input.recipient.reason === "mention"
-          ? "You received this because you were mentioned in this comment."
-          : "You received this because you participated in this comment thread.",
+  return {
+    subject: input.isReply
+      ? `${input.actor} replied to a comment on "${input.planTitle}"`
+      : `${input.actor} commented on "${input.planTitle}"`,
+    ...renderEmail({
+      preheader: `${input.actor} ${actionText} on ${input.app}.`,
+      heading: input.isReply
+        ? "New reply on your plan"
+        : "New comment on your plan",
+      paragraphs: [
+        `${emailStrong(input.actor)} ${actionText} ${emailStrong(input.planTitle)}.`,
+        `Comment: "${commentExcerpt(input.message)}"`,
+      ],
+      cta: { label: "Open plan", url: input.planUrl },
+      footer:
+        input.reason === "plan-owner"
+          ? "You received this because you own this plan."
+          : input.reason === "mention"
+            ? "You received this because you were mentioned in this comment."
+            : "You received this because you participated in this comment thread.",
+    }),
+  };
+}
+
+async function sendPlanCommentNotification(input: {
+  recipient: NotificationRecipient;
+  comment: PlanComment;
+  planTitle: string;
+  planId: string;
+}) {
+  await sendEmail({
+    ...renderPlanCommentEmail({
+      actor: actorName(input.comment),
+      app: appName(),
+      planTitle: input.planTitle,
+      planUrl: planUrl(input.planId),
+      message: input.comment.message,
+      isReply: Boolean(input.comment.parentCommentId),
+      reason: input.recipient.reason,
+    }),
+    to: input.recipient.email,
+    templateId: PLAN_COMMENT_EMAIL_ID,
   });
-  await sendEmail({ to: input.recipient.email, subject, html, text });
 }
 
 export async function notifyPlanCommentRecipients({

package/corpus/templates/plan/server/lib/emails.ts

@@ -0,0 +1,67 @@
+/**
+ * Catalog entries for the transactional emails Plan sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import {
+  PLAN_ACCESS_REQUEST_EMAIL_ID,
+  renderPlanAccessRequestEmail,
+} from "../../actions/request-plan-access.js";
+import {
+  PLAN_COMMENT_EMAIL_ID,
+  renderPlanCommentEmail,
+} from "./comment-notifications.js";
+
+let registered = false;
+
+export function registerPlanEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: PLAN_COMMENT_EMAIL_ID,
+    name: "Plan comment",
+    trigger:
+      "A human (never the agent) posts a comment or reply on a plan or recap. The subject changes for a reply and the body changes with why the recipient was picked; all variants send under this id.",
+    recipientLabel: "Owner, mentions, authors",
+    recipient:
+      "The plan owner, everyone mentioned in the comment, and — for a reply — every other human author in the same thread. The comment's own author, synthetic QA addresses, and the owner when the comment mentions the source author are all dropped. One email per remaining address.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderPlanCommentEmail({
+        actor: "Sam Rivera",
+        app: "Agent-Native Plan",
+        planTitle: "Checkout rewrite",
+        planUrl: "https://example.com/plans/plan_sample",
+        message: "Can we split the migration into two deploys?",
+        isReply: false,
+        reason: "plan-owner",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: PLAN_ACCESS_REQUEST_EMAIL_ID,
+    name: "Plan access request",
+    trigger:
+      "A signed-in user who cannot resolve access calls `request-plan-access` on a private plan URL. Skipped when email is not configured or the requester is the owner.",
+    recipientLabel: "Plan owner",
+    recipient:
+      "The plan's `ownerEmail` column. Anonymous public viewers and guest author identities cannot reach this path.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`, so the owner cannot reply straight to the requester.",
+    preview: () =>
+      renderPlanAccessRequestEmail({
+        requesterName: "Sam Rivera",
+        requesterEmail: "sam.rivera@example.com",
+        planTitle: "Checkout rewrite",
+        url: "https://example.com/plans/plan_sample",
+      }),
+  });
+}

package/corpus/templates/plan/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerPlanEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerPlanEmails();
+}

package/corpus/templates/slides/server/lib/comment-notifications.ts

@@ -21,6 +21,7 @@ import { and, eq } from "drizzle-orm";
 import { getDeckUrl } from "../../actions/_app-url.js";
 import { SLIDES_USER_PREFS_KEY } from "../../shared/slides-user-prefs.js";
 import { getDb, schema } from "../db/index.js";
+import { SLIDES_DECK_COMMENT_EMAIL_ID } from "./emails.js";
 
 /**
  * `deck-missing` stays distinct from `no-recipients`: one means the deck could
@@ -99,6 +100,41 @@ async function threadParticipants(
   return rows.map((row) => row.authorEmail);
 }
 
+export function renderDeckCommentEmail({
+  actor,
+  title,
+  url,
+  content,
+  isReply,
+}: {
+  actor: string;
+  title: string;
+  url: string;
+  content: string;
+  isReply: boolean;
+}) {
+  return {
+    subject: isReply
+      ? `${actor} replied to a comment on "${title}"`
+      : `${actor} commented on "${title}"`,
+    ...renderEmail({
+      preheader: isReply
+        ? `${actor} replied to a comment on ${title}.`
+        : `${actor} commented on ${title}.`,
+      heading: isReply ? "New reply on your deck" : "New comment",
+      paragraphs: [
+        isReply
+          ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(title)}.`
+          : `${emailStrong(actor)} commented on ${emailStrong(title)}.`,
+        `"${excerpt(content)}"`,
+      ],
+      cta: { label: "Open deck", url },
+      footer:
+        "You received this because you own or participated in this thread. Turn these off in Slides settings.",
+    }),
+  };
+}
+
 export async function notifyDeckComment(input: {
   deckId: string;
   slideId: string;
@@ -153,29 +189,16 @@ async function deliverDeckCommentEmails(input: {
     preferenceKey: SLIDES_USER_PREFS_KEY,
     logLabel: LOG_LABEL,
     send: async (to) => {
-      const { html, text } = renderEmail({
-        preheader: input.isReply
-          ? `${actor} replied to a comment on ${deck.title}.`
-          : `${actor} commented on ${deck.title}.`,
-        heading: input.isReply ? "New reply on your deck" : "New comment",
-        paragraphs: [
-          input.isReply
-            ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(deck.title)}.`
-            : `${emailStrong(actor)} commented on ${emailStrong(deck.title)}.`,
-          `"${excerpt(input.content)}"`,
-        ],
-        cta: { label: "Open deck", url },
-        footer:
-          "You received this because you own or participated in this thread. Turn these off in Slides settings.",
-      });
-
       await sendEmail({
+        ...renderDeckCommentEmail({
+          actor,
+          title: deck.title,
+          url,
+          content: input.content,
+          isReply: input.isReply,
+        }),
         to,
-        subject: input.isReply
-          ? `${actor} replied to a comment on "${deck.title}"`
-          : `${actor} commented on "${deck.title}"`,
-        html,
-        text,
+        templateId: SLIDES_DECK_COMMENT_EMAIL_ID,
       });
     },
   });

package/corpus/templates/slides/server/lib/emails.ts

@@ -0,0 +1,40 @@
+/**
+ * Catalog entries for the transactional emails Slides sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import { renderDeckCommentEmail } from "./comment-notifications.js";
+
+export const SLIDES_DECK_COMMENT_EMAIL_ID = "slides.deck-comment";
+
+let registered = false;
+
+export function registerSlidesEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: SLIDES_DECK_COMMENT_EMAIL_ID,
+    name: "Deck comment",
+    trigger:
+      "Someone posts a comment or a thread reply on a slide. Subject and copy differ slightly for a reply; both send under this id.",
+    recipientLabel: "Deck owner and authors",
+    recipient:
+      "The deck owner, plus every prior author in the thread when the new comment is a reply. The list is re-checked against the deck's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderDeckCommentEmail({
+        actor: "Sam Rivera",
+        title: "Series A narrative",
+        url: "https://example.com/decks/deck_sample?slide=3",
+        content: "Slide 3 needs the updated revenue chart before Thursday.",
+        isReply: false,
+      }),
+  });
+}

package/corpus/templates/slides/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerSlidesEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerSlidesEmails();
+}

package/dist/brand-kit/index.d.ts

@@ -16,6 +16,7 @@
  */
 export * from "./types.js";
 export * from "./brand-signals.js";
+export * from "./tokens.js";
 export { extractDesignTokensFromUrl, validateUrl, parseOwnerRepo, fetchGitHubJson, fetchGitHubJsonResult, fetchGitHubRaw, parseTailwindConfig, parseCss, detectStylingFramework, createCodeAnalysisState, analyzeCodeFile, analyzeCssFile, analyzeTailwindConfig, analyzeJsonTheme, analyzePackageJson, analyzeThemeSourceFile, addFont, extractCssVars, extractCodeColors, extractCodeFonts, extractDocumentColors, extractDocumentFonts, classifyFile, suggestionsForType, unique, MAX_FILES, MAX_FILE_SIZE, FETCH_TIMEOUT, ROOT_PATTERNS, SECONDARY_PATHS, CODE_MAX_FILES, CODE_MAX_TOTAL_BYTES, } from "../server/design-token-utils.js";
 export type { ContentType, ParsedCss, ParsedTailwindConfig, CodeAnalysisState, UrlExtractionResult, GitHubFetchOptions, GitHubJsonResult, } from "../server/design-token-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/brand-kit/index.js

@@ -16,6 +16,7 @@
  */
 export * from "./types.js";
 export * from "./brand-signals.js";
+export * from "./tokens.js";
 // Import-source parsing + token extraction (Tailwind/CSS/GitHub/URL/document/
 // code analysis). These already power the import-* actions across templates.
 export { 

package/dist/brand-kit/tokens.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `@agent-native/core/brand-kit/tokens`
+ *
+ * Pure helpers for the named-token vocabulary a Brand Kit stores alongside its
+ * seven color roles. Kept on its own subpath (no `design-token-utils` re-export)
+ * so browser code can import the CSS-safety predicates without pulling the
+ * server-side extraction stack into the bundle.
+ */
+import type { BrandKitToken, BrandKitTokenType } from "./types.js";
+/**
+ * Upper bound on a single kit's stored vocabulary. Large systems legitimately
+ * define hundreds of tokens; this only stops an unbounded scrape landing in SQL.
+ */
+export declare const MAX_BRAND_KIT_TOKENS = 500;
+export declare function isSafeCssVarName(value: string): boolean;
+/**
+ * Token values are spliced raw into `:root { … }` declarations, so anything that
+ * could terminate a declaration or break out of a `<style>` element is unsafe.
+ */
+export declare function isSafeCssTokenValue(value: string): boolean;
+export declare function isColorTokenValue(value: string): boolean;
+/**
+ * Bucket a token, trusting the value's shape over the name's keywords.
+ *
+ * Name-first classification called Primer's `--text-body-size-medium: 1rem` a
+ * color because the name contains "text", which then rendered a swatch with
+ * `background: 1rem`. A dimension is never a color however the token is named.
+ */
+export declare function classifyBrandKitToken(name: string, value: string): BrandKitTokenType;
+/** Title-case display name derived from a CSS var, e.g. `--primary-color`. */
+export declare function friendlyTokenName(cssVar: string): string;
+export type BrandKitTokenRejectionReason = "malformed" | "unsafe-css-var" | "unsafe-value" | "over-limit";
+export interface BrandKitTokenRejection {
+    reason: BrandKitTokenRejectionReason;
+    /** Best-effort identifier for the offending entry, for error messages. */
+    label: string;
+}
+export interface NormalizedBrandKitTokens {
+    tokens: BrandKitToken[];
+    /**
+     * Entries that could not be stored. Callers must surface these — a kit that
+     * silently kept 4 of 40 tokens reads downstream as a 4-token design system.
+     */
+    rejected: BrandKitTokenRejection[];
+}
+/**
+ * Coerce untrusted token JSON into storable tokens, reporting every entry it
+ * could not accept. Later duplicates of a `cssVar` win, matching the overlay
+ * order importers use.
+ */
+export declare function normalizeBrandKitTokens(input: unknown): NormalizedBrandKitTokens;
+/** Human-readable summary of why tokens were refused, for thrown errors. */
+export declare function describeBrandKitTokenRejections(rejected: readonly BrandKitTokenRejection[]): string;
+/**
+ * The seven colour roles plus radius/spacing, as tokens. Derived from a kit's
+ * summary fields rather than named by the source system, so they carry no
+ * `group`.
+ */
+export declare function brandKitRoleTokens(data: {
+    colors?: object | null;
+    borders?: {
+        radius?: string;
+    } | null;
+    spacing?: object | null;
+} | null | undefined, source?: string): BrandKitToken[];
+/**
+ * Read a kit's named tokens out of a raw CSS block. A kit's `customCSS` already
+ * spells out the source system's real token names. Declaration order wins on
+ * duplicates, matching the cascade.
+ */
+export declare function parseBrandKitTokensFromCss(css: string, source?: string): BrandKitToken[];
+/**
+ * The kit's named vocabulary: its stored `tokens` when it has them, else the
+ * names its `customCSS` declares. Kits predating `tokens` still carry real names
+ * in CSS, so reading only `tokens` would report them as having none.
+ */
+export declare function resolveBrandKitTokens(data: {
+    tokens?: unknown;
+    customCSS?: unknown;
+} | null | undefined, cssSource?: string): BrandKitToken[];
+export interface BrandKitTokenGroup {
+    /** The source's own group path when it has one, else the token type. */
+    label: string;
+    type: BrandKitTokenType;
+    tokens: BrandKitToken[];
+}
+/**
+ * Group tokens for display, preserving the source's collection paths. Groups sort
+ * by token type so colors lead, then alphabetically within a type.
+ */
+export declare function groupBrandKitTokens(tokens: readonly BrandKitToken[]): BrandKitTokenGroup[];
+//# sourceMappingURL=tokens.d.ts.map