feat: align local-first workspace direction

Document the VSCode-like local-first product shape, demote Convex to a control-plane role, and retire stale architecture drafts. Add local workspace migration/export references plus smoke coverage for no-Convex managed workspace startup, local markdown title/body/options persistence, asset upload behavior, and Convex fixture export. Verification: git diff --cached --check; node scripts/check-local-first-convex-guard.js --staged; node scripts/task444-convex-workspace-export-local-fixture-smoke.js; node scripts/task166-local-first-managed-workspace-no-convex-smoke.js; node scripts/task167-local-markdown-title-body-options-no-convex-smoke.js
2026-05-19 08:11:58 +08:00
parent 68d321e297
commit cdff672aa5
67 changed files with 5242 additions and 932 deletions
@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+const assert = require("assert");
+const fs = require("fs");
+const http = require("http");
+const net = require("net");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const TIMEOUT_MS = Number(process.env.UI_TIMEOUT_MS || 15_000);
+
+function pickPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = address && typeof address === "object" ? address.port : 0;
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}
+
+function waitForHttpOk(url, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve, reject) => {
+    const tick = () => {
+      const request = http.get(url, (response) => {
+        response.resume();
+        if (response.statusCode >= 200 && response.statusCode < 500) {
+          resolve();
+          return;
+        }
+        retry();
+      });
+      request.on("error", retry);
+      request.setTimeout(1_000, () => {
+        request.destroy();
+        retry();
+      });
+    };
+    const retry = () => {
+      if (Date.now() > deadline) {
+        reject(new Error(`server_not_ready: ${url}`));
+        return;
+      }
+      setTimeout(tick, 250);
+    };
+    tick();
+  });
+}
+
+function actorHeaders(actorId) {
+  return {
+    "content-type": "application/json",
+    "x-mnote-actor-id": actorId,
+    "x-mnote-actor-type": "user",
+  };
+}
+
+async function requestJson(baseUrl, actorId, pathname, options = {}) {
+  const response = await fetch(`${baseUrl}${pathname}`, {
+    method: options.method || "GET",
+    headers: actorHeaders(actorId),
+    body: options.body == null ? undefined : JSON.stringify(options.body),
+  });
+  const payload = await response.json().catch(() => null);
+  assert(
+    response.ok,
+    `${options.method || "GET"} ${pathname} failed ${response.status}: ${JSON.stringify(payload)}`,
+  );
+  return payload;
+}
+
+async function loadAggregate(baseUrl, actorId, documentId, rootUri) {
+  const url = new URL(`/api/page-aggregate/${encodeURIComponent(documentId)}`, baseUrl);
+  url.searchParams.set("sourceKind", "local_folder");
+  url.searchParams.set("rootUri", rootUri);
+  const payload = await requestJson(
+    baseUrl,
+    actorId,
+    `${url.pathname}${url.search}`,
+  );
+  return payload.result;
+}
+
+async function main() {
+  const port = await pickPort();
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const dataRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mnote-local-p3-"));
+  const actorId = `p3-smoke-${process.pid}-${Date.now()}`;
+  const managedRoot = path.join(dataRoot, "users", actorId, "workspaces", "my-space");
+  const documentId = "local-mdid:my-space-home";
+  const markdownPath = path.join(managedRoot, "pages", "我的空间.md");
+  const server = spawn("cargo", ["run", "-p", "mnote-web", "--bin", "mnote-web"], {
+    cwd: path.join(__dirname, "..", "rust"),
+    env: {
+      ...process.env,
+      MNOTE_WEB_BIND: `127.0.0.1:${port}`,
+      MNOTE_WEB_PUBLIC_BIND: `127.0.0.1:${port}`,
+      MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT: "0",
+      MNOTE_LOCAL_WORKSPACE_BASE_DIR: dataRoot,
+      CONVEX_SELF_HOSTED_URL: "http://127.0.0.1:9",
+      NEXT_PUBLIC_CONVEX_URL: "http://127.0.0.1:9",
+    },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let stderr = "";
+  server.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+
+  try {
+    await waitForHttpOk(`${baseUrl}/health`, 60_000);
+    const created = await requestJson(baseUrl, actorId, "/api/local-folder/workspaces/default", {
+      method: "POST",
+      body: {},
+    });
+    const rootUri = created.workspace.rootUri;
+    assert(rootUri, "创建默认本地工作区应返回 rootUri");
+
+    const firstAggregate = await loadAggregate(baseUrl, actorId, documentId, rootUri);
+    assert.equal(firstAggregate.head.title, "我的空间");
+
+    await requestJson(baseUrl, actorId, "/api/documents/title", {
+      method: "POST",
+      body: {
+        documentId,
+        sourceKind: "local_folder",
+        rootUri,
+        title: "P3 标题",
+      },
+    });
+
+    const afterTitle = await loadAggregate(baseUrl, actorId, documentId, rootUri);
+    const conflictDetectionKey = afterTitle.body.conflictDetectionKey || afterTitle.body.conflict_detection_key;
+    assert(conflictDetectionKey, "标题更新后应能读取新的 conflictDetectionKey");
+
+    await requestJson(baseUrl, actorId, "/api/documents/save", {
+      method: "POST",
+      body: {
+        documentId,
+        sourceKind: "local_folder",
+        rootUri,
+        conflictDetectionKey,
+        content: [
+          {
+            type: "heading",
+            props: { level: 1 },
+            content: [{ type: "text", text: "正文标题" }],
+          },
+          {
+            type: "paragraph",
+            content: [{ type: "text", text: "正文已保存" }],
+          },
+        ],
+      },
+    });
+
+    await requestJson(baseUrl, actorId, "/api/documents/options", {
+      method: "POST",
+      body: {
+        documentId,
+        sourceKind: "local_folder",
+        rootUri,
+        options: {
+          wideLayout: true,
+          showToc: true,
+          showHeadingNumbers: true,
+        },
+      },
+    });
+
+    const finalAggregate = await loadAggregate(baseUrl, actorId, documentId, rootUri);
+    assert.equal(finalAggregate.head.title, "P3 标题", "frontmatter title 应优先于正文 H1");
+    assert.equal(finalAggregate.layout.pageOptions.wideLayout, true);
+    assert.equal(finalAggregate.layout.pageOptions.showToc, true);
+    assert.equal(finalAggregate.layout.pageOptions.showHeadingNumbers, true);
+    assert(
+      JSON.stringify(finalAggregate.body.content).includes("正文已保存"),
+      "page aggregate 应从本地 markdown 恢复正文",
+    );
+
+    const markdown = fs.readFileSync(markdownPath, "utf8");
+    assert(markdown.includes("title: P3 标题"), "标题应写入 frontmatter");
+    assert(markdown.includes("# 正文标题"), "正文 H1 应写回 markdown");
+    assert(markdown.includes("正文已保存"), "正文段落应写回 markdown");
+    const options = fs.readFileSync(path.join(managedRoot, ".mnote", "page-options.json"), "utf8");
+    assert(options.includes("showToc"), "页面设置应写入 .mnote/page-options.json");
+
+    console.log("task167 local markdown title/body/options no-convex smoke passed");
+  } finally {
+    server.kill("SIGINT");
+    fs.rmSync(dataRoot, { recursive: true, force: true });
+    if (server.exitCode == null) {
+      await new Promise((resolve) => server.once("exit", resolve));
+    }
+    if (server.exitCode && server.exitCode !== 130 && server.exitCode !== null) {
+      process.stderr.write(stderr);
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});