@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/server/support.ts

@@ -0,0 +1,499 @@
+/**
+ * `handleSupportRequest`: the server side of the "Need help?" pill for a host with no tracker of its own.
+ * The twin of `handleSessionRequest`: one same-origin route in the host, with the host's secret kept there.
+ *
+ * The host calls it **after its own sign-in check** and says who the person is. Nothing here checks the
+ * host's sign-in, and nothing the browser sends is believed about who is asking: the reporter is the one in
+ * `config`, on every call.
+ *
+ * - `POST` (what `supportRequestsAt(url).submit` sends) files the request in Comment Tool with the
+ *   integration API's `fileReport`. The report's id is this helper's own: the reporter the host named and
+ *   the browser's id for the request, together (`reportIdOf`). So the same person sending a request again
+ *   files nothing twice, and nobody reaches another person's report by sending its id.
+ * - `GET` (what `supportRequestsAt(url).list` reads) answers the reporter's own requests from `reportsBy`:
+ *   their words and where each stands. Nothing written in the console is in that answer.
+ *
+ * What the person wrote is never logged here. A refusal is logged by its reason only.
+ */
+import {
+  HELP_BODY_BYTES,
+  HELP_ID,
+  HELP_IMAGE_TYPES,
+  HELP_LIMITS,
+  type HelpFailureWire,
+  type HelpImageType,
+  type HelpReceiptWire,
+} from "../help/wire.js";
+import type { SubmittedRequest, SubmittedRequestStatus } from "../help/types.js";
+
+export type SupportRequestConfig = {
+  /** Comment Tool: `https://comment-tool.example.com`. */
+  serviceUrl: string;
+  /** The host's connection token. Server only: it never reaches the browser. */
+  connectionToken: string;
+  /** The connection's own id for the project its support requests are filed in. */
+  project: string;
+  /** Who is asking, from the host's own sign-in. `userId` is the host's id for them. */
+  reporter: { userId: string; name: string };
+  /** The reporter's account in the host (a customer, a workspace), shown beside them in the console. */
+  account?: { id: string; name: string };
+  fetch?: typeof fetch;
+};
+
+// The integration API's shapes this helper writes and reads (`@comment-tool/contract`, `ops.ts`:
+// `FiledReport`, `fileReport`, `reportsBy`, `OwnReport`). Restated here because this package is published
+// on its own and takes nothing from the service's workspace.
+type FiledReport = {
+  reportId: string;
+  reporter: { userId: string; name: string };
+  account?: { id: string; name: string };
+  pageUrl?: string;
+  fields?: { label: string; value: string }[];
+  messages: {
+    id: string;
+    author: string;
+    role: "reporter";
+    body: string;
+    attachments?: { id: string; name: string; contentType: string; bytes: { $bytes: string } }[];
+  }[];
+};
+type FileReportResult = { refused?: readonly { id: string; reason: string }[] };
+type OwnReport = {
+  reportId: string;
+  createdAt: string;
+  status: "open" | "resolved";
+  title: string | null;
+  firstWords: string;
+  ticket: { displaySeq: number; status: string; statusLabel: string | null } | null;
+  /** Set while the team has the report merged into another of the same issue: where that one stands. */
+  consolidated?: {
+    status: "open" | "resolved";
+    ticket: { status: string; statusLabel: string | null } | null;
+  };
+};
+type ReportsByResult = { reports?: readonly Partial<OwnReport>[] };
+
+const HEADERS = { "cache-control": "no-store", "x-content-type-options": "nosniff" };
+
+const UNAVAILABLE = "Support requests are not available right now. Try again in a moment.";
+const TOO_MANY = "Too many requests right now. Try again in a few minutes.";
+const NOT_ACCEPTED = "The request could not be accepted. Check it and try again.";
+const UNREADABLE = "The request could not be read.";
+const TOO_LARGE = "That is too large to send. Remove a picture and try again.";
+const NOT_A_PICTURE = "Only pictures can be attached: PNG, JPEG or WebP.";
+const PICTURE_TOO_LARGE = "A picture is too large. Pictures can be up to 5 MB.";
+
+/** The service's limits for what this helper forwards (`apps/api/src/project/reports.ts`). */
+const SERVICE = { name: 80, accountName: 120, id: 200, fieldValue: 200 } as const;
+
+class Refusal extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function answer(body: unknown, status = 200, extra: Record<string, string> = {}): Response {
+  return Response.json(body, { status, headers: { ...HEADERS, ...extra } });
+}
+
+function failure(status: number, error: string, extra?: Record<string, string>): Response {
+  const body: HelpFailureWire = { error };
+  return answer(body, status, extra);
+}
+
+/**
+ * Text without the one character Comment Tool's database cannot hold. The service answers a text with a
+ * NUL in it as a failure of its own (HTTP 500), which a person could only meet again by sending again.
+ */
+function storable(value: string): string {
+  return value.replaceAll("\u0000", "");
+}
+
+function oneLine(value: unknown, limit: number): string {
+  return typeof value === "string"
+    ? storable(value).replace(/\s+/g, " ").trim().slice(0, limit)
+    : "";
+}
+
+/** An id the host gave, as the service takes one: 1 to 200 characters, none of them space or NUL. */
+function isId(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= SERVICE.id &&
+    !/\s/.test(value) &&
+    !value.includes("\u0000")
+  );
+}
+
+/** For the host's own logs: which call was refused and why, and never what the person wrote. */
+function note(op: string, reason: string): void {
+  // Server-side, in the host app: its logs are the only place a wrong token or project shows.
+  // oxlint-disable-next-line no-console
+  console.warn(`[comment-service] ${op} was refused: ${reason}.`);
+}
+
+/** The body, read no further than `limit` bytes. Null when it is longer. */
+async function bodyWithin(request: Request, limit: number): Promise<Uint8Array | null> {
+  if (Number(request.headers.get("content-length") ?? "0") > limit) return null;
+  if (!request.body) return new Uint8Array();
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+/** The type a file's first bytes say it is, whatever name or type it was sent with. */
+function sniff(head: Uint8Array): HelpImageType | null {
+  const starts = (...bytes: number[]) => bytes.every((byte, index) => head[index] === byte);
+  if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) return "image/png";
+  if (starts(0xff, 0xd8, 0xff)) return "image/jpeg";
+  if (
+    starts(0x52, 0x49, 0x46, 0x46) &&
+    head[8] === 0x57 &&
+    head[9] === 0x45 &&
+    head[10] === 0x42 &&
+    head[11] === 0x50
+  ) {
+    return "image/webp";
+  }
+  return null;
+}
+
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+
+function picture(given: unknown, index: number, taken: Set<string>) {
+  const image = (typeof given === "object" && given !== null ? given : {}) as Record<
+    string,
+    unknown
+  >;
+  const data = image["data"];
+  if (typeof data !== "string" || data.length === 0 || data.length % 4 !== 0) {
+    throw new Refusal(400, NOT_A_PICTURE);
+  }
+  // Judged by length before anything is decoded: four characters carry three bytes.
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  if ((data.length / 4) * 3 - padding > HELP_LIMITS.imageBytes) {
+    throw new Refusal(413, PICTURE_TOO_LARGE);
+  }
+  if (!BASE64.test(data)) throw new Refusal(400, NOT_A_PICTURE);
+  const head = Uint8Array.from(atob(data.slice(0, 16)), (character) => character.charCodeAt(0));
+  const contentType = sniff(head);
+  if (!contentType || !(HELP_IMAGE_TYPES as readonly string[]).includes(contentType)) {
+    throw new Refusal(415, NOT_A_PICTURE);
+  }
+  const extension = contentType.slice("image/".length).replace("jpeg", "jpg");
+  const name = oneLine(image["name"], HELP_LIMITS.name) || `picture-${index + 1}.${extension}`;
+  // The file's id within the report. A picture keeps its id when another is removed before a retry, so
+  // what was stored the first time is not stored again under a new one.
+  const stem = name.replace(/[^A-Za-z0-9._-]+/g, "_").slice(0, 150) || `picture-${index + 1}`;
+  let id = stem;
+  for (let copy = 2; taken.has(id); copy += 1) id = `${stem}-${copy}`;
+  taken.add(id);
+  return { id, name, contentType, bytes: { $bytes: data } };
+}
+
+/** The most a reporter's id may be to go into a report's id as it is: with `:` and a request's id, 200. */
+const OWNER_AS_IS = SERVICE.id - HELP_LIMITS.id - 1;
+
+/**
+ * The reporter's half of a report's id. Their id as the host gave it when that is safe: no `:`, so the
+ * first `:` of a report's id always ends this half; not starting `~`; and short enough that the whole id
+ * keeps to the service's 200 characters. Any other id goes in as `~` and its SHA-256 in base64url, 44
+ * characters, which no id taken as it is can equal. Two people never share a half.
+ */
+async function ownerOf(userId: string): Promise<string> {
+  if (userId.length <= OWNER_AS_IS && !userId.includes(":") && !userId.startsWith("~")) {
+    return userId;
+  }
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(userId)),
+  );
+  let binary = "";
+  for (const byte of digest) binary += String.fromCharCode(byte);
+  return `~${btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "")}`;
+}
+
+/**
+ * The report's id in Comment Tool for a request: `<the reporter's half>:<the browser's id>`. The browser
+ * chooses only the second half, so what it sends can name a report of the person the host says is asking
+ * and nobody else's.
+ */
+function reportIdOf(owner: string, id: string): string {
+  return `${owner}:${id}`;
+}
+
+/** The report to file for what the browser sent. Throws a `Refusal` for anything out of bounds. */
+function reportOf(given: unknown, config: SupportRequestConfig, owner: string): FiledReport {
+  if (typeof given !== "object" || given === null || Array.isArray(given)) {
+    throw new Refusal(400, UNREADABLE);
+  }
+  const sent = given as Record<string, unknown>;
+  const id = sent["id"];
+  if (
+    typeof id !== "string" ||
+    id.length === 0 ||
+    id.length > HELP_LIMITS.id ||
+    !HELP_ID.test(id)
+  ) {
+    throw new Refusal(400, NOT_ACCEPTED);
+  }
+  const message = typeof sent["message"] === "string" ? storable(sent["message"]).trim() : "";
+  if (message.length === 0) throw new Refusal(400, "Write what you need help with.");
+  if (message.length > HELP_LIMITS.message) {
+    throw new Refusal(400, "That is too long. Shorten it to 4,000 characters.");
+  }
+  const images: unknown = sent["images"] ?? [];
+  if (!Array.isArray(images)) throw new Refusal(400, NOT_ACCEPTED);
+  if (images.length > HELP_LIMITS.images) {
+    throw new Refusal(400, `At most ${HELP_LIMITS.images} pictures can be sent.`);
+  }
+  const taken = new Set<string>();
+  const attachments = images.map((image, index) => picture(image, index, taken));
+
+  const fields: { label: string; value: string }[] = [];
+  const field = (label: string, value: string) => {
+    if (value) fields.push({ label, value: value.slice(0, SERVICE.fieldValue) });
+  };
+  const pointed = sent["pointed"];
+  if (typeof pointed === "object" && pointed !== null) {
+    field("Pointed at", oneLine((pointed as { label?: unknown }).label, HELP_LIMITS.label));
+  }
+  const client = (
+    typeof sent["client"] === "object" && sent["client"] !== null ? sent["client"] : {}
+  ) as { userAgent?: unknown; language?: unknown; viewport?: unknown };
+  const viewport = (
+    typeof client.viewport === "object" && client.viewport !== null ? client.viewport : {}
+  ) as { width?: unknown; height?: unknown };
+  field("Browser", oneLine(client.userAgent, SERVICE.fieldValue));
+  if (Number.isFinite(viewport.width) && Number.isFinite(viewport.height)) {
+    field(
+      "Window",
+      `${Math.round(Number(viewport.width))} × ${Math.round(Number(viewport.height))}`,
+    );
+  }
+  field("Language", oneLine(client.language, 40));
+
+  let pageUrl: string | undefined;
+  const page = sent["pageUrl"];
+  if (typeof page === "string" && page.length <= HELP_LIMITS.url) {
+    try {
+      const url = new URL(page);
+      if (url.protocol === "http:" || url.protocol === "https:") pageUrl = url.href;
+    } catch {
+      // Not an address: the report is filed without one.
+    }
+  }
+  if (pageUrl && pageUrl.length > HELP_LIMITS.url) pageUrl = undefined;
+
+  const name = oneLine(config.reporter.name, SERVICE.name) || "Someone";
+  const account = config.account
+    ? { id: config.account.id, name: oneLine(config.account.name, SERVICE.accountName) }
+    : undefined;
+  return {
+    reportId: reportIdOf(owner, id),
+    reporter: { userId: config.reporter.userId, name },
+    ...(account?.name ? { account } : {}),
+    ...(pageUrl ? { pageUrl } : {}),
+    ...(fields.length > 0 ? { fields } : {}),
+    messages: [
+      {
+        id,
+        author: name,
+        role: "reporter",
+        body: message,
+        ...(attachments.length > 0 ? { attachments } : {}),
+      },
+    ],
+  };
+}
+
+/**
+ * One call of the integration API. Resolves with the op's value. Throws a `Refusal` carrying what the
+ * person is told: 502 when the service is down, wrongly configured or will not have this connection, 4xx
+ * when it refused what was sent.
+ */
+async function callOp<T>(config: SupportRequestConfig, op: string, input: unknown): Promise<T> {
+  const send = config.fetch ?? fetch;
+  let response: Response;
+  try {
+    response = await send(`${config.serviceUrl.replace(/\/+$/, "")}/api/v1/ops/${op}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.connectionToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ project: config.project, input }),
+    });
+  } catch {
+    note(op, "the service could not be reached");
+    throw new Refusal(502, UNAVAILABLE);
+  }
+  const payload = (await response.json().catch(() => null)) as {
+    ok?: unknown;
+    value?: unknown;
+    reason?: unknown;
+    error?: { code?: unknown };
+  } | null;
+  if (!response.ok) {
+    note(
+      op,
+      `HTTP ${response.status}${typeof payload?.error?.code === "string" ? ` ${payload.error.code}` : ""}`,
+    );
+    if (response.status === 413) throw new Refusal(413, TOO_LARGE);
+    if (response.status === 429) throw new Refusal(429, TOO_MANY);
+    throw new Refusal(502, UNAVAILABLE);
+  }
+  if (payload?.ok === true) return payload.value as T;
+  const reason =
+    typeof payload?.reason === "string" ? payload.reason : "an answer that could not be read";
+  note(op, reason);
+  if (reason === "invalid_input") throw new Refusal(400, NOT_ACCEPTED);
+  if (reason === "rate_limited") throw new Refusal(429, TOO_MANY);
+  throw new Refusal(502, UNAVAILABLE);
+}
+
+async function file(request: Request, config: SupportRequestConfig): Promise<Response> {
+  if (!/^application\/json\b/i.test(request.headers.get("content-type") ?? "")) {
+    return failure(415, UNREADABLE);
+  }
+  const body = await bodyWithin(request, HELP_BODY_BYTES);
+  if (body === null) return failure(413, TOO_LARGE);
+  let sent: unknown;
+  try {
+    sent = JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return failure(400, UNREADABLE);
+  }
+  const report = reportOf(sent, config, await ownerOf(config.reporter.userId));
+  const filed = await callOp<FileReportResult>(config, "fileReport", report);
+  const refused = Array.isArray(filed?.refused) ? filed.refused.length : 0;
+  const receipt: HelpReceiptWire =
+    refused === 0
+      ? {}
+      : {
+          note:
+            refused === 1
+              ? "1 picture could not be kept."
+              : `${refused} pictures could not be kept.`,
+        };
+  return answer(receipt);
+}
+
+/** What says where a report stands: the report itself, or the one it was merged into. */
+type Stands = {
+  status?: unknown;
+  ticket?: { status?: unknown; statusLabel?: unknown } | null;
+};
+
+/**
+ * The report whose standing the person is told. A report the team merged into another of the same issue
+ * stands where that other one does: its own thread was closed by the merge, and the issue may be open.
+ */
+function standingOf(report: Partial<OwnReport>): { stands: Stands; consolidated: boolean } {
+  const into: unknown = report.consolidated;
+  return typeof into === "object" && into !== null
+    ? { stands: into as Stands, consolidated: true }
+    : { stands: report, consolidated: false };
+}
+
+/**
+ * Where a report stands, in the pill's three words. A resolved report is `resolved`. An open one is
+ * `in_progress` once its ticket has left `new`, and `received` otherwise. A report with no ticket, which is
+ * every report this helper files, stays `received` until it is resolved: `reportsBy` says nothing of what a
+ * triager did in the console, on purpose, so there is nothing to tell "in progress" by.
+ */
+function statusOf(report: Stands): SubmittedRequestStatus {
+  if (report.status === "resolved") return "resolved";
+  const ticket = report.ticket?.status;
+  return typeof ticket === "string" && ticket !== "" && ticket !== "new"
+    ? "in_progress"
+    : "received";
+}
+
+async function list(config: SupportRequestConfig): Promise<Response> {
+  // A request is listed under the id its browser sent it with: the reporter's half of the report's id is
+  // this helper's business and is not sent back. A report the host filed for the person some other way
+  // keeps the id the host gave it.
+  const mine = reportIdOf(await ownerOf(config.reporter.userId), "");
+  const read = await callOp<ReportsByResult>(config, "reportsBy", {
+    reporterUserId: config.reporter.userId,
+    limit: HELP_LIMITS.listed,
+  });
+  const requests: SubmittedRequest[] = (Array.isArray(read?.reports) ? read.reports : [])
+    .filter(
+      (report) => typeof report?.reportId === "string" && typeof report.createdAt === "string",
+    )
+    .map((report) => {
+      const reportId = report.reportId as string;
+      const { stands, consolidated } = standingOf(report);
+      const label = oneLine(stands.ticket?.statusLabel, 80);
+      return {
+        id:
+          reportId.startsWith(mine) && reportId.length > mine.length
+            ? reportId.slice(mine.length)
+            : reportId,
+        ...(Number.isInteger(report.ticket?.displaySeq)
+          ? { reference: String(report.ticket?.displaySeq) }
+          : {}),
+        summary: oneLine(report.firstWords, 200) || oneLine(report.title, 200),
+        createdAt: report.createdAt as string,
+        status: statusOf(stands),
+        ...(label ? { statusLabel: label } : {}),
+        ...(consolidated ? { consolidated: true } : {}),
+      };
+    });
+  return answer({ requests });
+}
+
+export async function handleSupportRequest(
+  request: Request,
+  config: SupportRequestConfig,
+): Promise<Response> {
+  if (
+    !isId(config?.reporter?.userId) ||
+    !config.serviceUrl ||
+    !config.connectionToken ||
+    !config.project ||
+    (config.account !== undefined && !isId(config.account?.id))
+  ) {
+    // A host that calls this without saying who is asking has not done its sign-in check.
+    // oxlint-disable-next-line no-console
+    console.error(
+      "[comment-service] handleSupportRequest needs serviceUrl, connectionToken, project, reporter.userId and, when an account is given, its id.",
+    );
+    return failure(500, UNAVAILABLE);
+  }
+  try {
+    switch (request.method) {
+      case "POST":
+        return await file(request, config);
+      case "GET":
+        return await list(config);
+      default:
+        return failure(405, "Use GET or POST.", { allow: "GET, POST" });
+    }
+  } catch (error) {
+    if (error instanceof Refusal) return failure(error.status, error.message);
+    throw error;
+  }
+}

package/src/server.ts

@@ -0,0 +1,4 @@
+export { handleSessionRequest, readCommentServiceConfig } from "./server/index.js";
+export type { CommentServiceConfig } from "./server/index.js";
+export { handleSupportRequest } from "./server/support.js";
+export type { SupportRequestConfig } from "./server/support.js";

package/src/vite/plugin.ts

@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+
+import { CONFIG_KEY, annotateSource, buildConfigured, stampingEnabled } from "../compiler/index.js";
+import type { HostBuild } from "../runtime/debug-context-model.js";
+
+/** The constant `<CommentToolbar>` reads for the debug context's `build`, when nothing else gave one. */
+export const HOST_BUILD_CONSTANT = "__COMMENT_TOOL_HOST_BUILD__";
+
+/** Where CI systems put the commit being built, in the order they are read. */
+const COMMIT_VARIABLES = [
+  "COMMENT_SERVICE_BUILD_COMMIT",
+  "GITHUB_SHA",
+  "CF_PAGES_COMMIT_SHA",
+  "WORKERS_CI_COMMIT_SHA",
+  "VERCEL_GIT_COMMIT_SHA",
+  "CI_COMMIT_SHA",
+];
+
+/**
+ * The build this bundle is: the commit from the CI's variable or from `git`, the version from
+ * `COMMENT_SERVICE_BUILD_VERSION` or the package being built, and the mode. Only short, public facts.
+ */
+export function hostBuildOf(
+  mode: string,
+  root: string,
+  env: Record<string, string | undefined> = process.env,
+  git: () => string = () =>
+    execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }),
+): HostBuild {
+  let commit = COMMIT_VARIABLES.map((name) => env[name]?.trim()).find(Boolean);
+  if (!commit) {
+    try {
+      commit = git().trim();
+    } catch {
+      commit = undefined;
+    }
+  }
+  const short = commit && /^[0-9a-f]{7,40}$/i.test(commit) ? commit.slice(0, 12) : undefined;
+  const version = (env.COMMENT_SERVICE_BUILD_VERSION ?? env.npm_package_version)
+    ?.trim()
+    .slice(0, 64);
+  return {
+    ...(short ? { commit: short } : {}),
+    ...(version ? { version } : {}),
+    env: mode.slice(0, 40),
+    builtAt: new Date().toISOString(),
+  };
+}
+
+type ResolvedConfig = {
+  command: "build" | "serve";
+  mode: string;
+  logger: { info(message: string): void };
+};
+
+export function commentService(options?: { enabled?: boolean; root?: string }) {
+  const root = (options?.root ?? process.cwd()).replace(/\/$/, "");
+  let enabled = options?.enabled ?? process.env.COMMENT_SERVICE_ENABLED !== "0";
+  let told = false;
+  return {
+    name: "devaccel-comment-service",
+    enforce: "pre" as const,
+    // The build's commit and version, for the debug context of each comment (`<CommentToolbar debugContext>`).
+    config(_config: unknown, environment: { mode: string }) {
+      return {
+        define: { [HOST_BUILD_CONSTANT]: JSON.stringify(hostBuildOf(environment.mode, root)) },
+      };
+    },
+    configResolved(config: ResolvedConfig) {
+      enabled = stampingEnabled({
+        option: options?.enabled,
+        flag: process.env.COMMENT_SERVICE_ENABLED,
+        command: config.command,
+        configured: () => buildConfigured(root, config.mode),
+      });
+      if (config.command === "build" && !enabled && !told) {
+        told = true;
+        config.logger.info(
+          `[comment-service] This build sees no ${CONFIG_KEY}, so components are not stamped. ` +
+            "If it serves the comment toolbar, set COMMENT_SERVICE_ENABLED=1 or commentService({ enabled: true }).",
+        );
+      }
+    },
+    transform(code: string, id: string) {
+      if (!enabled) return null;
+      const file = id.split("?")[0];
+      if (!/\.[jt]sx$/.test(file) || file.includes("/node_modules/")) return null;
+      if (!file.startsWith(`${root}/`)) return null;
+      try {
+        const next = annotateSource(code, file, root);
+        return next === code ? null : { code: next, map: null };
+      } catch (error) {
+        console.warn("[comment-service] annotation skipped", file, error);
+        return null;
+      }
+    },
+  };
+}

package/src/vite.ts

@@ -0,0 +1 @@
+export { commentService } from "./vite/plugin.js";