docs: preserve parallel UniDesk updates

scripts/src/e2e.ts

@@ -96,6 +96,7 @@ const SERVICE_CHECK_NAMES = [
   "microservice:todo-note-health",
   "microservice:todo-note-migrated-data",
   "microservice:todo-note-write-path",
+  "microservice:todo-note-route-diagnostic",
   "microservice:code-queue-status",
   "microservice:code-queue-health",
   "microservice:code-queue-workdirs",
@@ -1761,6 +1762,68 @@ function runPsql(config: UniDeskConfig, sql: string): { ok: boolean; stdout: str
   return { ok: result.exitCode === 0, stdout: result.stdout.trim(), stderr: result.stderr.trim(), exitCode: result.exitCode };
 }
 
+function runTodoNoteCliProbe(args: string[]): { ok: boolean; exitCode: number | null; payload: unknown; stderr: string } {
+  const result = runCommand(["bun", "scripts/cli.ts", "microservice", "proxy", "todo-note", ...args], repoRoot, { timeoutMs: 30_000 });
+  let payload: unknown = null;
+  if (result.stdout.trim().length > 0) {
+    try {
+      payload = JSON.parse(result.stdout.trim()) as unknown;
+    } catch {
+      payload = null;
+    }
+  }
+  return { ok: result.exitCode === 0, exitCode: result.exitCode, payload, stderr: result.stderr.trim() };
+}
+
+function runTodoNoteRouteDiagnosticChecks(): { ok: boolean; detail: unknown } {
+  const issues: string[] = [];
+  // 1) Bad path: CLI must rewrite the misleading 404 to the structured diagnostic.
+  const badPathRewrite = runTodoNoteCliProbe(["/api/instances/instance_probe_bad/todos", "--method", "POST", "--body-json", JSON.stringify({ title: "e2e-route-diagnostic" })]);
+  const badPathBody = (badPathRewrite.payload as { data?: { body?: Record<string, unknown> } } | null)?.data?.body ?? null;
+  const rewriteOk = (
+    badPathRewrite.exitCode === 1
+    && badPathBody !== null
+    && badPathBody.error === "Todo Note route not found"
+    && badPathBody.backendOnly === true
+    && badPathBody.method === "POST"
+    && badPathBody.path === "/api/instances/instance_probe_bad/todos"
+    && Array.isArray(badPathBody.writableApiEndpoints)
+    && (badPathBody.writableApiEndpoints as Array<{ path?: string }>).some((endpoint) => endpoint.path === "/api/instances/:instanceId/actions")
+    && Array.isArray(badPathBody.actionTypes)
+    && (badPathBody.actionTypes as string[]).includes("addTodo")
+    && (badPathRewrite.payload as { data?: { bodyRewritten?: boolean } } | null)?.data?.bodyRewritten === true
+    && (badPathRewrite.payload as { data?: { upstreamBody?: { error?: string } } } | null)?.data?.upstreamBody?.error === "Todo Note is running in backend-only mode"
+  );
+  if (!rewriteOk) issues.push("bad-path-rewrite");
+  // 2) --check-path matched: POST /api/instances must succeed and return matched=true.
+  const checkPathMatched = runTodoNoteCliProbe(["/api/instances", "--method", "POST", "--check-path"]);
+  const checkPathMatchedData = (checkPathMatched.payload as { data?: { matched?: boolean; endpoint?: { path?: string } } } | null)?.data ?? null;
+  const matchOk = checkPathMatched.exitCode === 0 && checkPathMatchedData?.matched === true && checkPathMatchedData?.endpoint?.path === "/api/instances";
+  if (!matchOk) issues.push("check-path-match");
+  // 3) --check-path mismatched: must return the structured diagnostic and skip the upstream call.
+  const checkPathMissed = runTodoNoteCliProbe(["/api/todos", "--method", "POST", "--check-path"]);
+  const checkPathMissedData = (checkPathMissed.payload as { data?: { checkPath?: boolean; error?: string; path?: string } } | null)?.data ?? null;
+  const missOk = checkPathMissed.exitCode === 1 && checkPathMissedData?.checkPath === true && checkPathMissedData?.error === "Todo Note route not found" && checkPathMissedData?.path === "/api/todos";
+  if (!missOk) issues.push("check-path-miss");
+  // 4) --check-path on a non-todo-note service must return a structured unsupported error.
+  const unsupportedProbe = runCommand(["bun", "scripts/cli.ts", "microservice", "proxy", "code-queue", "/api/foo", "--method", "GET", "--check-path"], repoRoot, { timeoutMs: 30_000 });
+  let unsupportedPayload: unknown = null;
+  try { unsupportedPayload = JSON.parse(unsupportedProbe.stdout.trim()) as unknown; } catch { unsupportedPayload = null; }
+  const unsupportedData = (unsupportedPayload as { data?: { error?: string; supportedServices?: string[] } } | null)?.data ?? null;
+  const unsupportedOk = unsupportedProbe.exitCode === 1 && typeof unsupportedData?.error === "string" && unsupportedData.error.includes("--check-path currently only supports service=todo-note") && Array.isArray(unsupportedData.supportedServices) && unsupportedData.supportedServices.includes("todo-note");
+  if (!unsupportedOk) issues.push("check-path-unsupported");
+  return {
+    ok: issues.length === 0,
+    detail: {
+      issues,
+      badPathRewrite: { exitCode: badPathRewrite.exitCode, body: badPathBody },
+      checkPathMatched,
+      checkPathMissed: { exitCode: checkPathMissed.exitCode, data: checkPathMissedData },
+      unsupportedProbe: { exitCode: unsupportedProbe.exitCode, data: unsupportedData },
+    },
+  };
+}
+
 function dockerCoreJson(path: string, init?: { method?: string; body?: unknown }): unknown {
   const method = init?.method ?? "GET";
   const body = init?.body === undefined ? "" : JSON.stringify(init.body);
@@ -2474,6 +2537,10 @@ async function serviceChecks(config: UniDeskConfig, urls: PublicUrls, checks: E2
   addSelectedCheck(checks, options, "microservice:todo-note-health", (todoNoteHealth as { ok?: boolean; body?: { ok?: boolean; storage?: string } }).ok === true && (todoNoteHealth as { body?: { ok?: boolean; storage?: string } }).body?.ok === true && (todoNoteHealth as { body?: { storage?: string } }).body?.storage === "postgres", todoNoteHealth);
   addSelectedCheck(checks, options, "microservice:todo-note-migrated-data", (todoNoteInstances as { ok?: boolean }).ok === true && todoNoteRows.length >= 5 && ["CONSTAR", "大论文", "找工作", "小论文", "事务"].every((name) => todoNoteNames.includes(name)) && todoNoteRows.reduce((sum, row) => sum + Number(row.todoCount ?? 0), 0) >= 100, { todoNoteInstances });
   addSelectedCheck(checks, options, "microservice:todo-note-write-path", (todoNoteCreate as { ok?: boolean }).ok === true && (todoNoteAdd as { ok?: boolean }).ok === true && (todoNoteToggle as { ok?: boolean }).ok === true && (todoNoteUndo as { ok?: boolean }).ok === true && (todoNoteDelete as { ok?: boolean }).ok === true, { todoNoteCreate, todoNoteAdd, todoNoteToggle, todoNoteUndo, todoNoteDelete });
+  // Issue #198: assert the CLI-side rewrite of the Todo Note catch-all misleading 404.
+  // When the upstream fix lands, this gate will pass through the upstream body instead of the rewritten one — keep the assertion focused on the CLI-side shape (the upstream body is still preserved under upstreamBody so a future flip is auditable).
+  const todoNoteRouteDiagnostic = runTodoNoteRouteDiagnosticChecks();
+  addSelectedCheck(checks, options, "microservice:todo-note-route-diagnostic", todoNoteRouteDiagnostic.ok, todoNoteRouteDiagnostic.detail);
   addSelectedCheck(checks, options, "microservice:oa-event-flow-status", (oaEventFlowStatus as { ok?: boolean }).ok === true && (oaEventFlowStatus as { body?: { microservice?: { id?: string; providerId?: string } } }).body?.microservice?.providerId === config.providerGateway.id, oaEventFlowStatus);
   addSelectedCheck(checks, options, "microservice:oa-event-flow-health", (oaEventFlowHealth as { ok?: boolean }).ok === true && oaEventFlowHealthBody?.ok === true && oaEventFlowHealthBody.service === "oa-event-flow" && oaEventFlowHealthBody.databaseReady === true, oaEventFlowHealth);
   addSelectedCheck(checks, options, "microservice:oa-event-flow-diagnostics", (oaEventFlowDiagnostics as { ok?: boolean }).ok === true && oaEventFlowDiagnosticsBody?.ok === true && oaEventFlowDiagnosticsBody.service === "oa-event-flow" && oaEventFlowDiagnosticsBody.databaseReady === true && Number.isFinite(oaEventFlowDiagnosticsBody.eventCount) && Array.isArray(oaEventFlowDiagnosticsBody.eventTypes), oaEventFlowDiagnostics);