@agent-native/core 0.88.0 → 0.90.1

package/corpus/templates/plan/app/lib/plan-comment-editor-helpers.ts

@@ -0,0 +1,142 @@
+import { emailToName } from "@agent-native/core/client";
+import {
+  formatPlanCommentMentionToken,
+  type PlanCommentMention,
+  type PlanCommentResolutionTarget,
+} from "@shared/comment-context";
+
+export type CommentDraft = {
+  message: string;
+  mentions: PlanCommentMention[];
+  resolutionTarget: PlanCommentResolutionTarget;
+};
+
+export function displayNameForMention(email: string) {
+  return emailToName(email).replace(/\s+/g, " ").trim() || email;
+}
+
+export function createMentionChip(mention: PlanCommentMention) {
+  const chip = document.createElement("span");
+  chip.contentEditable = "false";
+  chip.dataset.mentionEmail = mention.email;
+  chip.dataset.mentionLabel = mention.label;
+  chip.className =
+    "inline-flex max-w-[12rem] items-center gap-1 rounded-full border border-primary/20 bg-primary/10 px-1.5 py-0.5 text-xs font-medium text-primary";
+  chip.textContent = `@${mention.label}`;
+  return chip;
+}
+
+export function appendMessageToEditor(root: HTMLElement, message: string) {
+  root.replaceChildren();
+  const pattern = /@\[([^\]]+)\]\(mailto:([^)]+)\)/g;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(message)) !== null) {
+    if (match.index > lastIndex) {
+      root.append(
+        document.createTextNode(message.slice(lastIndex, match.index)),
+      );
+    }
+    const label = match[1]?.trim();
+    const email = decodeURIComponent(match[2] ?? "")
+      .trim()
+      .toLowerCase();
+    if (label && email) {
+      root.append(createMentionChip({ label, email }));
+    }
+    lastIndex = pattern.lastIndex;
+  }
+  if (lastIndex < message.length) {
+    root.append(document.createTextNode(message.slice(lastIndex)));
+  }
+}
+
+export function serializeCommentEditor(root: HTMLElement) {
+  const serialize = (node: Node): string => {
+    if (node.nodeType === Node.TEXT_NODE) return node.textContent ?? "";
+    if (!(node instanceof HTMLElement)) return "";
+    const mentionEmail = node.dataset.mentionEmail;
+    if (mentionEmail) {
+      return formatPlanCommentMentionToken({
+        email: mentionEmail,
+        label: node.dataset.mentionLabel || displayNameForMention(mentionEmail),
+      });
+    }
+    if (node.tagName === "BR") return "\n";
+    return Array.from(node.childNodes).map(serialize).join("");
+  };
+  return Array.from(root.childNodes)
+    .map(serialize)
+    .join("")
+    .replace(/\u00a0/g, " ")
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+}
+
+export function commentBodyText(message: string) {
+  return message
+    .replace(/@\[([^\]]+)\]\(mailto:[^)]+\)/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function canSubmitInlineCommentDraft(input: {
+  draft: CommentDraft;
+  isSubmitting?: boolean;
+  lockToAgent?: boolean;
+}) {
+  const needsHumanMention =
+    !input.lockToAgent &&
+    input.draft.resolutionTarget === "human" &&
+    input.draft.mentions.length === 0;
+  return (
+    commentBodyText(input.draft.message).length > 0 &&
+    !needsHumanMention &&
+    !input.isSubmitting
+  );
+}
+
+export function mentionQueryAtCaret(root: HTMLElement) {
+  const selection = window.getSelection();
+  if (!selection || selection.rangeCount === 0) return null;
+  const range = selection.getRangeAt(0);
+  if (!range.collapsed || !root.contains(range.startContainer)) return null;
+  const textBeforeCaretRange = range.cloneRange();
+  textBeforeCaretRange.selectNodeContents(root);
+  textBeforeCaretRange.setEnd(range.startContainer, range.startOffset);
+  const text = textBeforeCaretRange.toString();
+  const match = /(?:^|\s)@([a-zA-Z0-9._+-]{0,64})$/.exec(text);
+  if (!match) return null;
+  const start = text.lastIndexOf("@");
+  const end = text.length;
+  const startPosition = textPositionInRoot(root, start);
+  const endPosition = textPositionInRoot(root, end);
+  if (!startPosition || !endPosition) return null;
+  const queryRange = document.createRange();
+  queryRange.setStart(startPosition.node, startPosition.offset);
+  queryRange.setEnd(endPosition.node, endPosition.offset);
+  return {
+    query: match[1] ?? "",
+    range: queryRange,
+  };
+}
+
+function textPositionInRoot(root: HTMLElement, offset: number) {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let seen = 0;
+  let lastText: Text | null = null;
+  let node = walker.nextNode() as Text | null;
+  while (node) {
+    const length = node.textContent?.length ?? 0;
+    if (offset <= seen + length) {
+      return { node, offset: Math.max(0, offset - seen) };
+    }
+    seen += length;
+    lastText = node;
+    node = walker.nextNode() as Text | null;
+  }
+  if (lastText && offset === seen) {
+    return { node: lastText, offset: lastText.textContent?.length ?? 0 };
+  }
+  return null;
+}

package/corpus/templates/plan/app/lib/plan-local-bridge.ts

@@ -0,0 +1,376 @@
+import { appPath } from "@agent-native/core/client";
+import { mimeTypeFromFilename } from "@shared/plan-assets";
+import type { PlanBlock, PlanContent } from "@shared/plan-content";
+import type { PlanBundle, PlanKind } from "@shared/types";
+
+import type { PlanCommentInput } from "@/hooks/use-plans";
+import type { PlanMdxFolder } from "@/lib/desktop-plan-files";
+
+import { parsePlanMdxFolder } from "../../server/plan-mdx";
+
+export type LocalPlanBundle = PlanBundle & {
+  localOnly: true;
+  slug: string;
+  folder: string;
+  repoPath?: string | null;
+  suggestedRepoPath?: string;
+  path?: string;
+  url?: string;
+  html?: string;
+  mdx?: PlanMdxFolder;
+};
+export type PlanBundleWithHtml =
+  | (PlanBundle & { html?: string })
+  | LocalPlanBundle;
+export type PlanCommentItem = PlanBundle["comments"][number];
+
+type LocalPlanBridgePayload = {
+  ok?: boolean;
+  version?: number;
+  source?: string;
+  localOnly?: boolean;
+  slug?: string;
+  dir?: string;
+  title?: string;
+  brief?: string;
+  kind?: PlanKind;
+  updatedAt?: string;
+  files?: string[];
+  mdx?: PlanMdxFolder;
+  comments?: PlanCommentItem[];
+  error?: string;
+};
+
+type LocalPlanBridgeCommentUpdate = {
+  comments?: PlanCommentInput[];
+  deletedCommentIds?: string[];
+};
+
+function assertLocalBridgeUrl(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Local plan bridge URL is invalid.");
+  }
+  const allowedHosts = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+  if (url.protocol !== "http:") {
+    throw new Error("Local plan bridge must use HTTP on localhost.");
+  }
+  if (!allowedHosts.has(url.hostname)) {
+    throw new Error("Local plan bridge must point to localhost.");
+  }
+  if (!url.port) {
+    throw new Error("Local plan bridge must use an explicit localhost port.");
+  }
+  if (url.username || url.password || url.hash) {
+    throw new Error("Local plan bridge URL contains unsupported credentials.");
+  }
+  if (url.pathname !== "/local-plan.json") {
+    throw new Error("Local plan bridge must point to /local-plan.json.");
+  }
+  const params = Array.from(url.searchParams.keys());
+  if (
+    params.length !== 1 ||
+    params[0] !== "token" ||
+    !url.searchParams.get("token")?.trim()
+  ) {
+    throw new Error("Local plan bridge URL is missing its access token.");
+  }
+  return url.toString();
+}
+
+function localPlanBridgeCommentsUrl(value: string): string {
+  const url = new URL(assertLocalBridgeUrl(value));
+  url.pathname = "/local-plan-comments.json";
+  return url.toString();
+}
+
+const LOCAL_PLAN_BRIDGE_MAX_RETRIES = 5;
+
+export function shouldRetryLocalPlanBridgeBundle(
+  failureCount: number,
+  error: unknown,
+) {
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  if (
+    message.includes("Local plan bridge URL") ||
+    message.includes("Local plan bridge must") ||
+    message.includes("Local plan bridge response was not")
+  ) {
+    return false;
+  }
+  return failureCount < LOCAL_PLAN_BRIDGE_MAX_RETRIES;
+}
+
+export function localPlanBridgeRetryDelay(attemptIndex: number) {
+  return Math.min(500 * 2 ** attemptIndex, 2_500);
+}
+
+/**
+ * Decide whether the hosted-plan render should surface the retryable load
+ * error card instead of the initial skeleton.
+ *
+ * A React Query read can be *paused* (browser offline, or the tab blurred
+ * during a retry backoff): in that state it never errors and never resolves,
+ * so `isError`/`isLoading`/`isFetching` are all false and `data` stays
+ * undefined. Without treating that as an error-like state the page sits on the
+ * initial skeleton forever until a manual refresh — exactly the "wasn't
+ * loading the content until I do another refresh" report. Surfacing the
+ * retry card lets the user recover; React Query also auto-resumes the paused
+ * fetch when the network/tab returns, which clears the card on its own.
+ */
+export function shouldShowPlanLoadError(input: {
+  hasSelectedId: boolean;
+  localPlanMode: boolean;
+  hasBundle: boolean;
+  planQueryInitialPending: boolean;
+  planQueryError: boolean;
+  planQueryPaused: boolean;
+  accessStatusInitialPending: boolean;
+  accessStatusPaused: boolean;
+  accessDenied: boolean;
+}): boolean {
+  if (!input.hasSelectedId || input.localPlanMode || input.hasBundle) {
+    return false;
+  }
+  if (input.planQueryError) return true;
+  if (!input.accessStatusInitialPending && input.accessDenied) return true;
+  // While the first read is actively in flight, keep showing the skeleton.
+  // Background refetches must not hide a settled access/error card.
+  if (input.planQueryInitialPending || input.accessStatusInitialPending) {
+    return false;
+  }
+  // Paused/stalled read that will never settle on its own input.
+  if (input.planQueryPaused || input.accessStatusPaused) return true;
+  return false;
+}
+
+export function localPlanRoutePath(
+  slug: string,
+  repoPath?: string | null,
+): string {
+  const base = appPath(`/local-plans/${encodeURIComponent(slug)}`);
+  if (!repoPath) return base;
+  const params = new URLSearchParams({ path: repoPath });
+  return `${base}?${params.toString()}`;
+}
+
+export function localPlanRouteUrl(
+  slug: string,
+  repoPath?: string | null,
+): string {
+  const path = localPlanRoutePath(slug, repoPath);
+  return typeof window === "undefined"
+    ? path
+    : `${window.location.origin}${path}`;
+}
+
+function localPlanAssetDataUrl(
+  url: string | undefined,
+  assets: Record<string, string> | undefined,
+): string | undefined {
+  if (!url || !assets) return url;
+  const match = url.match(/^(?:\.\/)?assets\/(.+)$/);
+  const filename = match?.[1];
+  if (!filename) return url;
+  const base64 = assets[filename];
+  if (!base64) return url;
+  const mime = mimeTypeFromFilename(filename);
+  if (!mime) return url;
+  return `data:${mime};base64,${base64}`;
+}
+
+function inlineLocalPlanAssets(
+  content: PlanContent,
+  assets: Record<string, string> | undefined,
+): PlanContent {
+  if (!assets || Object.keys(assets).length === 0) return content;
+  const rewriteBlocks = (blocks: PlanBlock[]): PlanBlock[] =>
+    blocks.map((block): PlanBlock => {
+      if (block.type === "image") {
+        return {
+          ...block,
+          data: {
+            ...block.data,
+            url: localPlanAssetDataUrl(block.data.url, assets),
+            assetId: undefined,
+          },
+        };
+      }
+      if (block.type === "tabs") {
+        return {
+          ...block,
+          data: {
+            ...block.data,
+            tabs: block.data.tabs.map((tab) => ({
+              ...tab,
+              blocks: rewriteBlocks(tab.blocks),
+            })),
+          },
+        };
+      }
+      if (block.type === "columns") {
+        return {
+          ...block,
+          data: {
+            ...block.data,
+            columns: block.data.columns.map((column) => ({
+              ...column,
+              blocks: rewriteBlocks(column.blocks),
+            })),
+          },
+        };
+      }
+      return block;
+    });
+  return { ...content, blocks: rewriteBlocks(content.blocks) };
+}
+
+function countLocalPlanBlocks(blocks: PlanBlock[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  const visitBlocks = (items: PlanBlock[]) => {
+    for (const block of items) {
+      counts[block.type] = (counts[block.type] ?? 0) + 1;
+      if (block.type === "tabs") {
+        for (const tab of block.data.tabs) visitBlocks(tab.blocks);
+      } else if (block.type === "columns") {
+        for (const column of block.data.columns) visitBlocks(column.blocks);
+      }
+    }
+  };
+  visitBlocks(blocks);
+  return counts;
+}
+
+export function localPlanBridgeQueryKey(slug: string, bridgeUrl: string) {
+  return ["local-plan-bridge", slug, bridgeUrl] as const;
+}
+
+// Merge folder comments.json onto a read-only bridge bundle (which serves none);
+// the bundle's own comments win so optimistic/just-written ones aren't clobbered.
+export function mergeLocalBridgeComments(
+  bundle: LocalPlanBundle | undefined,
+  folderComments: LocalPlanBundle["comments"] | undefined,
+): LocalPlanBundle | undefined {
+  if (!bundle) return bundle;
+  const comments =
+    bundle.comments.length > 0 ? bundle.comments : (folderComments ?? []);
+  if (comments === bundle.comments) return bundle;
+  return {
+    ...bundle,
+    comments,
+    summary: {
+      ...bundle.summary,
+      commentCount: comments.length,
+      openCommentCount: comments.filter((c) => c.status === "open").length,
+    },
+  };
+}
+
+async function localPlanBridgePayloadToBundle(
+  payload: LocalPlanBridgePayload,
+  fallbackSlug: string,
+): Promise<LocalPlanBundle> {
+  if (
+    payload.source !== "agent-native-local-bridge" ||
+    !payload.mdx?.["plan.mdx"]
+  ) {
+    throw new Error("Local plan bridge response was not a Plan MDX folder.");
+  }
+
+  const rawContent = await parsePlanMdxFolder(payload.mdx, {
+    salvageInvalidBlocks: payload.kind === "recap",
+  });
+  const content = inlineLocalPlanAssets(rawContent, payload.mdx["assets/"]);
+  const now = payload.updatedAt || new Date().toISOString();
+  const slug = payload.slug || fallbackSlug || "local-plan";
+  const kind = payload.kind === "recap" ? "recap" : "plan";
+  const title = content.title || payload.title || slug;
+  const brief = content.brief || payload.brief || "";
+  const url = localPlanRouteUrl(slug);
+  const comments = (payload.comments ?? []).filter(
+    (comment) => !comment.deletedAt,
+  );
+  const bundle: LocalPlanBundle = {
+    plan: {
+      id: `local-${slug}`,
+      title,
+      brief,
+      kind,
+      status: "review",
+      source: "imported",
+      repoPath: payload.dir ?? null,
+      currentFocus: "local-files preview",
+      html: null,
+      markdown: payload.mdx["plan.mdx"],
+      content,
+      createdAt: now,
+      updatedAt: now,
+      approvedAt: null,
+    },
+    access: {
+      role: "viewer",
+      ownerEmail: null,
+      orgId: null,
+      visibility: "private",
+    },
+    sections: [],
+    comments,
+    events: [],
+    summary: {
+      sectionCounts: countLocalPlanBlocks(content.blocks),
+      commentCount: comments.length,
+      openCommentCount: comments.filter((comment) => comment.status === "open")
+        .length,
+    },
+    localOnly: true,
+    slug,
+    folder: payload.dir ?? slug,
+    path: `/local-plans/${encodeURIComponent(slug)}`,
+    url,
+    mdx: payload.mdx,
+  };
+  return bundle;
+}
+
+export async function fetchLocalPlanBridgeBundle(
+  bridgeUrl: string,
+  fallbackSlug: string,
+): Promise<LocalPlanBundle> {
+  const safeUrl = assertLocalBridgeUrl(bridgeUrl);
+  const response = await fetch(safeUrl, { cache: "no-store" });
+  const payload = (await response
+    .json()
+    .catch(() => null)) as LocalPlanBridgePayload | null;
+  if (!response.ok || !payload?.ok) {
+    throw new Error(
+      payload?.error ||
+        `Local plan bridge returned ${response.status || "an error"}.`,
+    );
+  }
+  return localPlanBridgePayloadToBundle(payload, fallbackSlug);
+}
+
+export async function updateLocalPlanBridgeComments(
+  bridgeUrl: string,
+  fallbackSlug: string,
+  update: LocalPlanBridgeCommentUpdate,
+): Promise<LocalPlanBundle> {
+  const response = await fetch(localPlanBridgeCommentsUrl(bridgeUrl), {
+    method: "POST",
+    cache: "no-store",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(update),
+  });
+  const payload = (await response
+    .json()
+    .catch(() => null)) as LocalPlanBridgePayload | null;
+  if (!response.ok || !payload?.ok) {
+    throw new Error(
+      payload?.error ||
+        `Local plan bridge returned ${response.status || "an error"}.`,
+    );
+  }
+  return localPlanBridgePayloadToBundle(payload, fallbackSlug);
+}