@agent-native/core 0.85.7 → 0.86.0

package/corpus/core/src/cli/plan-local.ts

@@ -74,6 +74,52 @@ type LocalPlanBridgeMdxFolder = {
   "assets/"?: Record<string, string>;
 };
 
+type LocalPlanBridgeComment = {
+  id: string;
+  planId: string;
+  parentCommentId: string | null;
+  sectionId: string | null;
+  kind: string;
+  status: string;
+  anchor: string | null;
+  message: string;
+  createdBy: string;
+  authorEmail: string | null;
+  authorName: string | null;
+  resolutionTarget: string | null;
+  mentions: unknown[];
+  mentionsJson: string | null;
+  resolvedBy: string | null;
+  resolvedAt: string | null;
+  consumedAt: string | null;
+  deletedAt: string | null;
+  deletedBy: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type LocalPlanBridgeCommentInput = {
+  id?: string;
+  parentCommentId?: string | null;
+  sectionId?: string | null;
+  kind?: string;
+  status?: string;
+  anchor?: string | null;
+  message?: string;
+  createdBy?: string;
+  authorEmail?: string | null;
+  authorName?: string | null;
+  resolutionTarget?: string | null;
+  mentions?: unknown[];
+  resolvedBy?: string | null;
+  resolvedAt?: string | null;
+};
+
+type LocalPlanBridgeCommentUpdate = {
+  comments?: LocalPlanBridgeCommentInput[];
+  deletedCommentIds?: string[];
+};
+
 type VisualAnswerSourcePayload = {
   question?: string;
   title?: string;
@@ -117,6 +163,7 @@ export type LocalPlanBridgePayload = {
   updatedAt: string;
   files: string[];
   mdx: LocalPlanBridgeMdxFolder;
+  comments: LocalPlanBridgeComment[];
 };
 
 export type LocalPlanServeResult = {
@@ -191,6 +238,10 @@ type OpenLocalUrlResult = {
   error?: string;
 };
 
+const LOCAL_PLAN_COMMENTS_FILE = "comments.json";
+const LOCAL_PLAN_OWNER_EMAIL = "local@agent-native.local";
+const LOCAL_PLAN_BRIDGE_COMMENT_BODY_LIMIT = 1024 * 1024;
+
 const LOCAL_PLAN_ASSET_MAX_SINGLE_BYTES = 2 * 1024 * 1024;
 const LOCAL_PLAN_ASSET_MAX_TOTAL_BYTES = 10 * 1024 * 1024;
 const AGENT_NATIVE_MANIFEST_FILE = "agent-native.json";
@@ -1905,6 +1956,154 @@ export function writeLocalPlanPreview(input: {
   };
 }
 
+function readLocalPlanBridgeComments(dir: string): LocalPlanBridgeComment[] {
+  try {
+    const raw = fs.readFileSync(
+      path.join(dir, LOCAL_PLAN_COMMENTS_FILE),
+      "utf-8",
+    );
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed)
+      ? (parsed as LocalPlanBridgeComment[]).filter(
+          (comment) => comment && typeof comment.id === "string",
+        )
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeLocalPlanBridgeComments(
+  dir: string,
+  comments: LocalPlanBridgeComment[],
+): void {
+  const target = path.join(dir, LOCAL_PLAN_COMMENTS_FILE);
+  if (comments.length === 0) {
+    fs.rmSync(target, { force: true });
+    return;
+  }
+  fs.writeFileSync(target, `${JSON.stringify(comments, null, 2)}\n`, "utf-8");
+}
+
+function normalizeBridgeCommentString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function normalizeBridgeCommentNullableString(value: unknown): string | null {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text || null;
+}
+
+function normalizeBridgeCommentStatus(value: unknown): string {
+  return value === "resolved" ? "resolved" : "open";
+}
+
+function newLocalBridgeCommentId(): string {
+  return `cmt_${crypto.randomBytes(8).toString("hex")}`;
+}
+
+function applyLocalPlanBridgeCommentUpdate(
+  dir: string,
+  update: LocalPlanBridgeCommentUpdate,
+): LocalPlanBridgeComment[] {
+  const existing = readLocalPlanBridgeComments(dir);
+  const byId = new Map(existing.map((comment) => [comment.id, comment]));
+  const now = new Date().toISOString();
+  const planId = `local-${path.basename(dir)}`;
+
+  for (const input of update.comments ?? []) {
+    const id =
+      normalizeBridgeCommentNullableString(input.id) ??
+      newLocalBridgeCommentId();
+    const prev = byId.get(id);
+    const status = normalizeBridgeCommentStatus(input.status ?? prev?.status);
+    const message =
+      typeof input.message === "string" ? input.message : prev?.message;
+    if (!message?.trim()) continue;
+
+    if (prev) {
+      byId.set(id, {
+        ...prev,
+        parentCommentId:
+          normalizeBridgeCommentNullableString(input.parentCommentId) ??
+          prev.parentCommentId,
+        sectionId:
+          normalizeBridgeCommentNullableString(input.sectionId) ??
+          prev.sectionId,
+        kind: normalizeBridgeCommentString(input.kind, prev.kind),
+        status,
+        anchor:
+          typeof input.anchor === "string" || input.anchor === null
+            ? input.anchor
+            : prev.anchor,
+        message,
+        authorEmail:
+          normalizeBridgeCommentNullableString(input.authorEmail) ??
+          prev.authorEmail,
+        authorName:
+          normalizeBridgeCommentNullableString(input.authorName) ??
+          prev.authorName,
+        resolutionTarget: "agent",
+        mentions: [],
+        mentionsJson: null,
+        resolvedAt:
+          status === "resolved"
+            ? (input.resolvedAt ?? prev.resolvedAt ?? now)
+            : null,
+        resolvedBy:
+          status === "resolved"
+            ? (input.resolvedBy ?? prev.resolvedBy ?? LOCAL_PLAN_OWNER_EMAIL)
+            : null,
+        updatedAt: now,
+      });
+      continue;
+    }
+
+    byId.set(id, {
+      id,
+      planId,
+      parentCommentId: normalizeBridgeCommentNullableString(
+        input.parentCommentId,
+      ),
+      sectionId: normalizeBridgeCommentNullableString(input.sectionId),
+      kind: normalizeBridgeCommentString(input.kind, "annotation"),
+      status,
+      anchor: normalizeBridgeCommentNullableString(input.anchor),
+      message,
+      createdBy: "human",
+      authorEmail:
+        normalizeBridgeCommentNullableString(input.authorEmail) ??
+        LOCAL_PLAN_OWNER_EMAIL,
+      authorName: normalizeBridgeCommentNullableString(input.authorName),
+      resolutionTarget: "agent",
+      mentions: [],
+      mentionsJson: null,
+      resolvedBy: status === "resolved" ? LOCAL_PLAN_OWNER_EMAIL : null,
+      resolvedAt: status === "resolved" ? now : null,
+      consumedAt: null,
+      deletedAt: null,
+      deletedBy: null,
+      createdAt: now,
+      updatedAt: now,
+    });
+  }
+
+  for (const id of update.deletedCommentIds ?? []) {
+    byId.delete(id);
+    for (const comment of byId.values()) {
+      if (comment.parentCommentId === id) byId.delete(comment.id);
+    }
+  }
+
+  const comments = [...byId.values()].sort((a, b) =>
+    a.createdAt === b.createdAt
+      ? a.id.localeCompare(b.id)
+      : a.createdAt.localeCompare(b.createdAt),
+  );
+  writeLocalPlanBridgeComments(dir, comments);
+  return comments;
+}
+
 function buildLocalPlanBridgePayload(input: {
   dir: string;
   kind?: LocalPlanKind;
@@ -1925,6 +2124,7 @@ function buildLocalPlanBridgePayload(input: {
     firstHeading(parsed.body) ||
     path.basename(dir);
   const brief = input.brief || parsed.frontmatter.brief || "";
+  const comments = readLocalPlanBridgeComments(dir);
 
   return {
     ok: true,
@@ -1939,6 +2139,7 @@ function buildLocalPlanBridgePayload(input: {
     updatedAt: latestLocalPlanMtime(dir, files),
     files: localPlanFileList(files),
     mdx: localPlanMdxFolder(files),
+    comments,
   };
 }
 
@@ -1948,6 +2149,7 @@ function latestLocalPlanMtime(dir: string, files: LocalPlanFiles): string {
     ...(files.canvasMdx ? [path.join(dir, "canvas.mdx")] : []),
     ...(files.prototypeMdx ? [path.join(dir, "prototype.mdx")] : []),
     ...(files.stateJson ? [path.join(dir, ".plan-state.json")] : []),
+    path.join(dir, LOCAL_PLAN_COMMENTS_FILE),
     ...Object.keys(files.assets ?? {}).map((filename) =>
       path.join(dir, "assets", filename),
     ),
@@ -1970,7 +2172,7 @@ function sendBridgeJson(
 ): void {
   res.writeHead(status, {
     "access-control-allow-origin": "*",
-    "access-control-allow-methods": "GET, OPTIONS",
+    "access-control-allow-methods": "GET, POST, OPTIONS",
     "access-control-allow-headers": "content-type",
     // Required when the hosted HTTPS Plan UI fetches this localhost bridge.
     "access-control-allow-private-network": "true",
@@ -1981,6 +2183,45 @@ function sendBridgeJson(
   res.end(`${JSON.stringify(payload)}\n`);
 }
 
+function readBridgeJsonBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    req.setEncoding("utf-8");
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > LOCAL_PLAN_BRIDGE_COMMENT_BODY_LIMIT) {
+        reject(new Error("Local plan comment update is too large."));
+        req.destroy();
+      }
+    });
+    req.on("end", () => {
+      if (!raw.trim()) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Local plan comment update must be JSON."));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function normalizeBridgeCommentUpdatePayload(
+  payload: unknown,
+): LocalPlanBridgeCommentUpdate {
+  if (!payload || typeof payload !== "object") return {};
+  const input = payload as LocalPlanBridgeCommentUpdate;
+  return {
+    comments: Array.isArray(input.comments) ? input.comments : [],
+    deletedCommentIds: Array.isArray(input.deletedCommentIds)
+      ? input.deletedCommentIds.filter((id) => typeof id === "string")
+      : [],
+  };
+}
+
 function bridgeRequestUrl(req: IncomingMessage): URL {
   return new URL(req.url || "/", "http://127.0.0.1");
 }
@@ -2020,13 +2261,12 @@ export async function startLocalPlanBridge(input: {
       sendBridgeJson(res, 204, "");
       return;
     }
-    if (req.method !== "GET") {
-      sendBridgeJson(res, 405, { ok: false, error: "Method not allowed." });
-      return;
-    }
 
     const url = bridgeRequestUrl(req);
-    if (url.pathname !== "/local-plan.json") {
+    if (
+      url.pathname !== "/local-plan.json" &&
+      url.pathname !== "/local-plan-comments.json"
+    ) {
       sendBridgeJson(res, 404, { ok: false, error: "Not found." });
       return;
     }
@@ -2034,25 +2274,42 @@ export async function startLocalPlanBridge(input: {
       sendBridgeJson(res, 403, { ok: false, error: "Invalid bridge token." });
       return;
     }
-
-    try {
-      sendBridgeJson(
-        res,
-        200,
-        buildLocalPlanBridgePayload({
-          dir,
-          kind: input.kind,
-          title: input.title,
-          brief: input.brief,
-          skipSourceValidation: input.skipSourceValidation,
-        }),
-      );
-    } catch (error) {
-      sendBridgeJson(res, 500, {
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      });
+    if (url.pathname === "/local-plan.json" && req.method !== "GET") {
+      sendBridgeJson(res, 405, { ok: false, error: "Method not allowed." });
+      return;
     }
+    if (url.pathname === "/local-plan-comments.json" && req.method !== "POST") {
+      sendBridgeJson(res, 405, { ok: false, error: "Method not allowed." });
+      return;
+    }
+
+    void (async () => {
+      try {
+        if (url.pathname === "/local-plan-comments.json") {
+          const body = await readBridgeJsonBody(req);
+          applyLocalPlanBridgeCommentUpdate(
+            dir,
+            normalizeBridgeCommentUpdatePayload(body),
+          );
+        }
+        sendBridgeJson(
+          res,
+          200,
+          buildLocalPlanBridgePayload({
+            dir,
+            kind: input.kind,
+            title: input.title,
+            brief: input.brief,
+            skipSourceValidation: input.skipSourceValidation,
+          }),
+        );
+      } catch (error) {
+        sendBridgeJson(res, 500, {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    })();
   });
 
   await new Promise<void>((resolve, reject) => {