Merge pull request #91 from CodeForPhilly/feat/markdown-transforms

feat: markdown @mention + external-link transforms (closes #81)

Author: themightychris

.env.example

@@ -79,3 +79,14 @@ CFP_JWT_SIGNING_KEY=change-me-to-a-random-string-at-least-32-chars
 # serves the SPA as a fallthrough for non-/api/* routes (single-image
 # deploy per specs/architecture.md). Leave unset in dev — Vite owns 5173.
 # CFP_WEB_DIST_PATH=/app/apps/web/dist
+
+# ---------------------------------------------------------------------------
+# Markdown rendering
+# ---------------------------------------------------------------------------
+
+# Public-facing host. Used by the server-side markdown renderer's
+# external-link transform — anchors with a host different from this one
+# get target="_blank" rel="noopener nofollow". See
+# specs/behaviors/markdown-rendering.md. Sandbox: next-v2.codeforphilly.org.
+# Production: codeforphilly.org (the default).
+# CFP_SITE_HOST=codeforphilly.org

apps/api/src/app.ts

@@ -37,6 +37,7 @@ import storePlugin from './plugins/store.js';
 import reconcilePlugin from './plugins/reconcile.js';
 import pushDaemonPlugin from './plugins/push-daemon.js';
 import servicesPlugin from './plugins/services.js';
+import markdownPlugin from './plugins/markdown.js';
 import rateLimitPlugin from './plugins/rate-limit.js';
 import idempotencyPlugin from './plugins/idempotency.js';
 import sessionMiddlewarePlugin from './auth/middleware.js';
@@ -129,6 +130,7 @@ export async function buildApp(opts: BuildAppOptions = {}): Promise<FastifyInsta
 
   // ----- 6c. Services (loads in-memory state + FTS, boots after store) -----
   await fastify.register(servicesPlugin);
+  await fastify.register(markdownPlugin);
 
   // ----- 7. Rate limiting -----
   await fastify.register(rateLimitPlugin);

apps/api/src/env.ts

@@ -59,6 +59,14 @@ export const EnvSchema = z.object({
    * image; unset in dev (Vite owns 5173).
    */
   CFP_WEB_DIST_PATH: z.string().optional(),
+  /**
+   * Host of the public-facing site (e.g. `codeforphilly.org` in prod,
+   * `next-v2.codeforphilly.org` in sandbox). Used by the server-side
+   * markdown renderer to distinguish internal from external links — anchors
+   * with a host different from this one get `target="_blank" rel="noopener
+   * nofollow"`. Per specs/behaviors/markdown-rendering.md.
+   */
+  CFP_SITE_HOST: z.string().default('codeforphilly.org'),
 });
 
 export type Env = z.infer<typeof EnvSchema>;
@@ -95,5 +103,6 @@ export const envJsonSchema = {
     SAML_CERTIFICATE: { type: 'string' },
     SLACK_TEAM_HOST: { type: 'string', default: 'codeforphilly.slack.com' },
     CFP_WEB_DIST_PATH: { type: 'string' },
+    CFP_SITE_HOST: { type: 'string', default: 'codeforphilly.org' },
   },
 } as const;

apps/api/src/plugins/markdown.ts

@@ -0,0 +1,44 @@
+/**
+ * Markdown plugin.
+ *
+ * Installs a `renderMarkdown` implementation into
+ * `apps/api/src/services/serializers/common.ts` that closes over:
+ *
+ *   - `CFP_SITE_HOST` (from env) — used by the external-link transform
+ *     to decide which anchors get `target="_blank" rel="noopener nofollow"`.
+ *   - `inMemoryState.personIdBySlug.has` — used by the `@mention` transform
+ *     to resolve which usernames link to a real Person.
+ *
+ * Every serializer renders markdown via `common.renderMarkdown`, which
+ * dispatches to whichever function this plugin most recently installed.
+ * Until installed (tests, ad-hoc scripts), it falls back to the bare
+ * `@cfp/shared` renderer — same output as before, no transforms.
+ *
+ * Per specs/behaviors/markdown-rendering.md.
+ */
+import { renderMarkdown } from '@cfp/shared';
+import type { FastifyInstance } from 'fastify';
+import fp from 'fastify-plugin';
+
+import { setRenderMarkdown } from '../services/serializers/common.js';
+
+async function markdownPlugin(fastify: FastifyInstance): Promise<void> {
+  const siteHost = fastify.config.CFP_SITE_HOST;
+  // Closure over the LIVE inMemoryState reference (not its value) so the
+  // resolver always sees the current Map even after hot-reload swaps state
+  // in place. (Hot reload preserves `state` identity per
+  // specs/behaviors/storage.md#hot-reload — the Maps are mutated in place,
+  // not replaced.)
+  const state = fastify.inMemoryState;
+  setRenderMarkdown((source) =>
+    renderMarkdown(source, {
+      siteHost,
+      resolveMention: (slug) => state.personIdBySlug.has(slug),
+    }),
+  );
+}
+
+export default fp(markdownPlugin, {
+  name: 'markdown',
+  dependencies: ['services'],
+});

apps/api/src/routes/preview.ts

@@ -10,7 +10,7 @@
  * editor preview path.
  */
 import type { FastifyInstance } from 'fastify';
-import { renderMarkdown } from '@cfp/shared';
+import { renderMarkdown } from '../services/serializers/common.js';
 import { ok } from '../lib/response.js';
 import { ApiValidationError } from '../lib/errors.js';
 

apps/api/src/services/serializers/common.ts

@@ -1,9 +1,37 @@
 /**
  * Shared serialization helpers used across entity serializers.
  */
-import { renderMarkdown } from '@cfp/shared';
+import { renderMarkdown as rawRenderMarkdown, type RenderMarkdownResult } from '@cfp/shared';
 import type { Person, Tag } from '@cfp/shared/schemas';
 
+/**
+ * Boot-installed renderer. Defaults to the bare `@cfp/shared` pipeline so
+ * tests + dev code that import serializers directly without booting the
+ * markdown plugin keep working. The markdown plugin
+ * (`apps/api/src/plugins/markdown.ts`) calls `setRenderMarkdown` at boot
+ * to swap in a renderer bound to `CFP_SITE_HOST` + the live
+ * `inMemoryState.personIdBySlug` lookup, so all serializer output applies
+ * the external-link + `@mention` transforms from
+ * specs/behaviors/markdown-rendering.md.
+ *
+ * Module-level state is justified here over per-call threading: every
+ * serializer currently routes through `renderMarkdown(source)` without
+ * carrying an `app` or `FastifyInstance` reference, and a per-process
+ * single binding matches the runtime's actual shape (one Fastify app,
+ * one renderer config). Hot-reload preserves the state Maps in place so
+ * the closure stays correct.
+ */
+let currentRender: (source: string) => RenderMarkdownResult = rawRenderMarkdown;
+
+export function setRenderMarkdown(fn: (source: string) => RenderMarkdownResult): void {
+  currentRender = fn;
+}
+
+/** Render a markdown source through the boot-installed renderer. */
+export function renderMarkdown(source: string): RenderMarkdownResult {
+  return currentRender(source);
+}
+
 /** PersonAvatar shape used in many nested contexts. */
 export interface PersonAvatar {
   readonly slug: string;
@@ -53,12 +81,6 @@ export function groupTagsByNamespace(
   return { topic, tech, event };
 }
 
-/** Render markdown to HTML + an excerpt. Returns empty string for null/empty source. */
-export function renderField(source: string | null | undefined): { html: string; excerpt: string } {
-  if (!source) return { html: '', excerpt: '' };
-  const { html, excerpt } = renderMarkdown(source);
-  return { html, excerpt };
-}
 
 /** Truncate a plain-text string at a word boundary. */
 export function truncate(text: string, maxLength: number): string {

apps/api/src/services/serializers/help-wanted.ts

@@ -2,9 +2,8 @@
  * HelpWantedRole serializer.
  */
 import type { HelpWantedRole, Person, Project, Tag, TagAssignment } from '@cfp/shared/schemas';
-import { renderMarkdown } from '@cfp/shared';
 import type { HelpWantedPermissions } from '../permissions.js';
-import { groupTagsByNamespace, serializePersonAvatar, type TagItem } from './common.js';
+import { groupTagsByNamespace, renderMarkdown, serializePersonAvatar, type TagItem } from './common.js';
 
 export interface HelpWantedRoleResponse {
   readonly id: string;

apps/api/src/services/serializers/person.ts

@@ -9,8 +9,8 @@ import type {
   Tag,
   TagAssignment,
 } from '@cfp/shared/schemas';
-import { renderMarkdown } from '@cfp/shared';
 import type { PersonPermissions } from '../permissions.js';
+import { renderMarkdown } from './common.js';
 import {
   groupTagsByNamespace,
   serializePersonAvatar,

apps/api/src/services/serializers/project-buzz.ts

@@ -2,9 +2,8 @@
  * ProjectBuzz serializer.
  */
 import type { Person, Project, ProjectBuzz } from '@cfp/shared/schemas';
-import { renderMarkdown } from '@cfp/shared';
 import type { BuzzPermissions } from '../permissions.js';
-import { serializePersonAvatar } from './common.js';
+import { renderMarkdown, serializePersonAvatar } from './common.js';
 
 export interface ProjectBuzzResponse {
   readonly id: string;

apps/api/src/services/serializers/project-update.ts

@@ -2,9 +2,8 @@
  * ProjectUpdate serializer.
  */
 import type { Person, Project, ProjectUpdate } from '@cfp/shared/schemas';
-import { renderMarkdown } from '@cfp/shared';
 import type { UpdatePermissions } from '../permissions.js';
-import { serializePersonAvatar } from './common.js';
+import { renderMarkdown, serializePersonAvatar } from './common.js';
 
 export interface ProjectUpdateResponse {
   readonly id: string;