plugin-build-guide-block 1.1.4 → 1.1.6

package/dist/server/actions/build.js

@@ -36,7 +36,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var build_exports = {};
 __export(build_exports, {
-  build: () => build
+  WORKER_JOB_BUILD_GUIDE_PROCESS: () => WORKER_JOB_BUILD_GUIDE_PROCESS,
+  build: () => build,
+  recoverInterruptedBuilds: () => recoverInterruptedBuilds,
+  registerBuildGuideQueue: () => registerBuildGuideQueue,
+  unregisterBuildGuideQueue: () => unregisterBuildGuideQueue
 });
 module.exports = __toCommonJS(build_exports);
 var import_sanitize_html = __toESM(require("sanitize-html"));
@@ -50,6 +54,66 @@ const MAX_SOURCE_CHARS = 9e4;
 const MIN_CHAPTERS = 1;
 const MAX_CHAPTERS = 12;
 const DEFAULT_TARGET_CHAPTERS = 5;
+const WORKER_JOB_BUILD_GUIDE_PROCESS = "build-guide:process";
+const BUILD_GUIDE_QUEUE_CHANNEL = "plugin-build-guide-block.build";
+const BUILD_GUIDE_QUEUE_CONCURRENCY = Math.max(
+  1,
+  Number.parseInt(process.env.BUILD_GUIDE_QUEUE_CONCURRENCY || process.env.BUILD_GUIDE_MAX_CONCURRENCY || "1", 10) || 1
+);
+const BUILD_GUIDE_QUEUE_TIMEOUT_MS = Math.max(
+  6e4,
+  Number.parseInt(process.env.BUILD_GUIDE_QUEUE_TIMEOUT_MS || "", 10) || 30 * 60 * 1e3
+);
+const BUILD_GUIDE_QUEUE_POLL_INTERVAL_MS = Math.max(
+  1e3,
+  Number.parseInt(process.env.BUILD_GUIDE_QUEUE_POLL_INTERVAL_MS || "", 10) || 5e3
+);
+const BUILD_GUIDE_QUEUE_WAKE_CHANNEL = "plugin-build-guide-block.build.wake";
+const BUILD_GUIDE_QUEUE_REDIS_CONNECTION = "plugin-build-guide-block.build.queue";
+const BUILD_TRIGGER_LOCK_TTL_MS = 3e4;
+const BUILD_RUN_LOCK_TTL_MS = Math.max(
+  6e4,
+  Number.parseInt(process.env.BUILD_GUIDE_RUN_LOCK_TTL_MS || "", 10) || 24 * 60 * 60 * 1e3
+);
+const BUILD_HEARTBEAT_INTERVAL_MS = Math.max(
+  5e3,
+  Number.parseInt(process.env.BUILD_GUIDE_HEARTBEAT_MS || "", 10) || 3e4
+);
+const BUILD_STALE_MS = Math.max(
+  BUILD_HEARTBEAT_INTERVAL_MS * 2,
+  Number.parseInt(process.env.BUILD_GUIDE_STALE_MS || "", 10) || 12e4
+);
+const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".txt",
+  ".md",
+  ".markdown",
+  ".csv",
+  ".tsv",
+  ".json",
+  ".xml",
+  ".html",
+  ".htm",
+  ".yaml",
+  ".yml",
+  ".log",
+  ".sql",
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".css",
+  ".scss",
+  ".less"
+]);
+const TEXT_MIMETYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "application/x-yaml",
+  "application/javascript",
+  "application/typescript",
+  "image/svg+xml"
+]);
 const SANITIZE_OPTIONS = {
   allowedTags: [
     "div",
@@ -94,12 +158,93 @@ const SANITIZE_OPTIONS = {
     }
   }
 };
+let buildQueueTimer = null;
+let buildQueueKickTimer = null;
+let buildQueueProcessing = false;
+let buildQueueWakeHandler = null;
+class StaleBuildRunError extends Error {
+  constructor(spaceId, runId) {
+    super(`Build run ${runId} for space ${spaceId} is no longer current`);
+    this.name = "StaleBuildRunError";
+  }
+}
 function clampChapterCount(value) {
   const count = Number(value);
   if (!Number.isFinite(count)) return DEFAULT_TARGET_CHAPTERS;
   return Math.max(MIN_CHAPTERS, Math.min(MAX_CHAPTERS, Math.round(count)));
 }
-async function fetchFileContent(app, file) {
+function resolveExtname(file) {
+  const explicit = file == null ? void 0 : file.extname;
+  if (typeof explicit === "string" && explicit) return explicit.toLowerCase();
+  const name = (file == null ? void 0 : file.filename) || (file == null ? void 0 : file.name) || "";
+  const index = String(name).lastIndexOf(".");
+  return index >= 0 ? String(name).slice(index).toLowerCase() : "";
+}
+function isTextDocument(file) {
+  const mimetype = String((file == null ? void 0 : file.mimetype) || "").toLowerCase();
+  if (mimetype.startsWith("text/")) return true;
+  if (TEXT_MIMETYPES.has(mimetype)) return true;
+  return TEXT_EXTENSIONS.has(resolveExtname(file));
+}
+function createParserContext(app) {
+  const headers = { "x-timezone": "+00:00", "x-locale": "en-US" };
+  return {
+    app,
+    db: app.db,
+    log: app.log || app.logger || console,
+    logger: app.logger || app.log || console,
+    state: {},
+    auth: {},
+    req: { headers },
+    request: { headers },
+    get(name) {
+      return headers[String(name).toLowerCase()] || "";
+    },
+    getCurrentLocale() {
+      return "en-US";
+    },
+    t(key) {
+      return key;
+    },
+    i18n: {
+      t(key) {
+        return key;
+      }
+    }
+  };
+}
+function extractParsedText(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map(extractParsedText).filter(Boolean).join("\n");
+  }
+  if (typeof value === "object") {
+    if (typeof value.text === "string") return value.text;
+    if (typeof value.content === "string") return value.content;
+    if (value.content) return extractParsedText(value.content);
+    if (value.message) return extractParsedText(value.message);
+  }
+  return "";
+}
+function getDocumentParserPlugin(app) {
+  var _a, _b, _c, _d;
+  return ((_b = (_a = app.pm) == null ? void 0 : _a.get) == null ? void 0 : _b.call(_a, "@nocobase/plugin-document-parser")) || ((_d = (_c = app.pm) == null ? void 0 : _c.get) == null ? void 0 : _d.call(_c, "plugin-document-parser")) || null;
+}
+function unsupportedDocumentMessage(file) {
+  const filename = (file == null ? void 0 : file.filename) || (file == null ? void 0 : file.name) || (file == null ? void 0 : file.id) || "document";
+  const type = (file == null ? void 0 : file.mimetype) || resolveExtname(file) || "unknown type";
+  return `[Unsupported document type: ${filename} (${type}). Install or enable plugin-document-parser/MarkItDown to extract this file.]`;
+}
+async function fetchTextFileContent(app, file) {
+  if (!isTextDocument(file)) {
+    return unsupportedDocumentMessage(file);
+  }
+  const docParserPlugin = getDocumentParserPlugin(app);
+  if (docParserPlugin == null ? void 0 : docParserPlugin.fetchFileBuffer) {
+    const { buffer } = await docParserPlugin.fetchFileBuffer(createParserContext(app), file);
+    return buffer.toString("utf8");
+  }
   const fileManager = app.pm.get("file-manager");
   if (!fileManager) return "";
   const url = await fileManager.getFileURL(file);
@@ -119,6 +264,42 @@ async function fetchFileContent(app, file) {
     return `[Failed to read document: ${file.filename}]`;
   }
 }
+async function parseWithDocumentParser(app, file) {
+  var _a, _b, _c, _d, _e;
+  const docParserPlugin = getDocumentParserPlugin(app);
+  if (!docParserPlugin) return "";
+  const parserCtx = createParserContext(app);
+  const defaultParser = async () => ({
+    placement: "contentBlocks",
+    content: {
+      type: "text",
+      text: await fetchTextFileContent(app, file)
+    }
+  });
+  try {
+    if ((_a = docParserPlugin.parseRouter) == null ? void 0 : _a.route) {
+      const result = await docParserPlugin.parseRouter.route(parserCtx, file, defaultParser);
+      const text = extractParsedText(result == null ? void 0 : result.content);
+      if (text && !text.startsWith("[Unsupported document type:")) {
+        return text;
+      }
+    }
+    if ((_b = docParserPlugin.internalParserRegistry) == null ? void 0 : _b.parse) {
+      const result = await docParserPlugin.internalParserRegistry.parse(file, parserCtx);
+      if ((result == null ? void 0 : result.handled) && ((_c = result == null ? void 0 : result.text) == null ? void 0 : _c.trim())) {
+        return result.text;
+      }
+    }
+  } catch (err) {
+    (_e = (_d = app.log) == null ? void 0 : _d.warn) == null ? void 0 : _e.call(_d, `[plugin-build-guide-block] Document parser failed for ${(file == null ? void 0 : file.filename) || (file == null ? void 0 : file.id)}`, err);
+  }
+  return "";
+}
+async function fetchFileContent(app, file) {
+  const parsedText = await parseWithDocumentParser(app, file);
+  if (parsedText) return parsedText;
+  return fetchTextFileContent(app, file);
+}
 function toPlainText(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value)) {
@@ -319,59 +500,114 @@ ${content}
   );
   return texts.join("\n");
 }
-async function runBuild(app, db, filterByTk) {
+function getSpaceModel(app) {
+  return app.db.getModel("aiBuildGuideSpaces");
+}
+async function updateSpaceForRun(app, run, values, optional = false) {
+  const SpaceModel = getSpaceModel(app);
+  const [affected] = await SpaceModel.update(values, {
+    where: {
+      id: run.spaceId,
+      buildRunId: run.runId
+    }
+  });
+  if (!affected && !optional) {
+    throw new StaleBuildRunError(run.spaceId, run.runId);
+  }
+  return affected > 0;
+}
+async function claimBuildRun(app, run, workerId) {
+  const now = /* @__PURE__ */ new Date();
+  const SpaceModel = getSpaceModel(app);
+  const [affected] = await SpaceModel.update(
+    {
+      buildPhase: "running",
+      buildStartedAt: now,
+      buildHeartbeatAt: now,
+      buildWorkerId: workerId
+    },
+    {
+      where: {
+        id: run.spaceId,
+        status: "building",
+        buildPhase: "queued",
+        buildRunId: run.runId
+      }
+    }
+  );
+  return affected > 0;
+}
+function getBuildWorkerId(app) {
+  return [
+    process.env.HOSTNAME || process.env.COMPUTERNAME || "worker",
+    app.name || "app",
+    app.instanceId || "0",
+    process.pid
+  ].join(":");
+}
+function startBuildHeartbeat(app, run) {
+  const timer = setInterval(() => {
+    updateSpaceForRun(
+      app,
+      run,
+      {
+        buildHeartbeatAt: /* @__PURE__ */ new Date()
+      },
+      true
+    ).catch((error) => {
+      var _a, _b;
+      (_b = (_a = app.log) == null ? void 0 : _a.warn) == null ? void 0 : _b.call(_a, `[plugin-build-guide-block] Failed to update heartbeat for build ${run.runId}`, error);
+    });
+  }, BUILD_HEARTBEAT_INTERVAL_MS);
+  return () => clearInterval(timer);
+}
+async function runBuild(app, db, run) {
   const spaceRepo = db.getRepository("aiBuildGuideSpaces");
   const pageRepo = db.getRepository("aiBuildGuidePages");
-  const space = await spaceRepo.findById(filterByTk);
+  const space = await spaceRepo.findById(run.spaceId);
   if (!space) {
     throw new Error("Space not found");
   }
+  if (space.get("buildRunId") !== run.runId) {
+    throw new StaleBuildRunError(run.spaceId, run.runId);
+  }
   const { llmService, model } = space.get();
   if (!llmService || !model) {
     throw new Error("LLM Service or model is missing in space configuration");
   }
   await pageRepo.destroy({
     filter: {
-      spaceId: filterByTk
+      spaceId: run.spaceId
     }
   });
-  await spaceRepo.update({
-    filterByTk,
-    values: {
-      buildPhase: "reading",
-      buildLog: "Reading source documents",
-      generatedHtml: null,
-      generatedMarkdown: null,
-      planJson: null,
-      pageCount: 0
-    }
+  await updateSpaceForRun(app, run, {
+    buildPhase: "reading",
+    buildLog: "Reading source documents",
+    generatedHtml: null,
+    generatedMarkdown: null,
+    planJson: null,
+    pageCount: 0
   });
   const documentsText = await readDocuments(app, space);
   const sourceHash = import_crypto.default.createHash("sha256").update(documentsText).digest("hex");
   const provider = await getLLMProvider(app, llmService, model);
-  await spaceRepo.update({
-    filterByTk,
-    values: {
-      buildPhase: "planning",
-      buildLog: "Creating guide breakdown plan",
-      sourceHash
-    }
+  await updateSpaceForRun(app, run, {
+    buildPhase: "planning",
+    buildLog: "Creating guide breakdown plan",
+    sourceHash
   });
   const plan = await buildPlan(provider, space, documentsText);
-  await spaceRepo.update({
-    filterByTk,
-    values: {
-      planJson: plan,
-      pageCount: plan.chapters.length,
-      buildPhase: "building_pages",
-      buildLog: `Plan created with ${plan.chapters.length} chapters`
-    }
+  await updateSpaceForRun(app, run, {
+    planJson: plan,
+    pageCount: plan.chapters.length,
+    buildPhase: "building_pages",
+    buildLog: `Plan created with ${plan.chapters.length} chapters`
   });
   const pageRecords = [];
   for (const [index, chapter] of plan.chapters.entries()) {
     const page = await pageRepo.create({
       values: {
-        spaceId: filterByTk,
+        spaceId: run.spaceId,
         sort: index + 1,
         title: chapter.title,
         slug: slugify(chapter.title, `chapter-${index + 1}`),
@@ -392,12 +628,9 @@ async function runBuild(app, db, filterByTk) {
         buildLog: "Building chapter with LLM"
       }
     });
-    await spaceRepo.update({
-      filterByTk,
-      values: {
-        buildPhase: "building_pages",
-        buildLog: `Building chapter ${index + 1}/${pageRecords.length}: ${chapter.title}`
-      }
+    await updateSpaceForRun(app, run, {
+      buildPhase: "building_pages",
+      buildLog: `Building chapter ${index + 1}/${pageRecords.length}: ${chapter.title}`
     });
     try {
       const markdown = await buildPageMarkdown(provider, space, plan, chapter, documentsText);
@@ -424,76 +657,442 @@ async function runBuild(app, db, filterByTk) {
   }
   const completedPages = await pageRepo.find({
     filter: {
-      spaceId: filterByTk,
+      spaceId: run.spaceId,
       status: "completed"
     },
     sort: ["sort"]
   });
   const combinedMarkdown = completedPages.map((page) => page.get("generatedMarkdown")).filter(Boolean).join("\n\n---\n\n");
   const combinedHtml = await markdownToCleanHtml(combinedMarkdown);
-  await spaceRepo.update({
-    filterByTk,
+  await updateSpaceForRun(app, run, {
+    status: "completed",
+    buildPhase: "completed",
+    buildLog: `Built ${completedPages.length} chapters successfully`,
+    generatedMarkdown: combinedMarkdown,
+    generatedHtml: combinedHtml,
+    buildHeartbeatAt: /* @__PURE__ */ new Date()
+  });
+}
+function isBuildGuideWorker(app) {
+  const workerMode = process.env.WORKER_MODE || "";
+  return app.serving(WORKER_JOB_BUILD_GUIDE_PROCESS) || workerMode === "worker" || workerMode === "task" || process.env.APP_ROLE === "worker";
+}
+function clearLocalBuildMemoryQueue(app) {
+  var _a, _b, _c, _d, _e;
+  const eventQueue = app.eventQueue;
+  const adapter = eventQueue == null ? void 0 : eventQueue.adapter;
+  const fullChannel = (_a = eventQueue == null ? void 0 : eventQueue.getFullChannel) == null ? void 0 : _a.call(eventQueue, BUILD_GUIDE_QUEUE_CHANNEL);
+  const queue = fullChannel ? (_c = (_b = adapter == null ? void 0 : adapter.queues) == null ? void 0 : _b.get) == null ? void 0 : _c.call(_b, fullChannel) : null;
+  if (!(queue == null ? void 0 : queue.length)) return;
+  adapter.queues.set(fullChannel, []);
+  (_e = (_d = app.log) == null ? void 0 : _d.warn) == null ? void 0 : _e.call(
+    _d,
+    `[plugin-build-guide-block] Cleared ${queue.length} stale local memory message(s) on non-worker node; queued DB builds will be picked up by workers`
+  );
+}
+function getBuildQueueRedisKey(app) {
+  const appName = app.name || process.env.APP_NAME || "main";
+  return `${appName}:plugin-build-guide-block:build:queue`;
+}
+async function getBuildQueueRedis(app) {
+  var _a, _b;
+  const manager = app.redisConnectionManager;
+  if (!(manager == null ? void 0 : manager.getConnectionSync)) {
+    return null;
+  }
+  try {
+    const connectionString = process.env.QUEUE_ADAPTER_REDIS_URL || process.env.REDIS_URL;
+    return await manager.getConnectionSync(
+      BUILD_GUIDE_QUEUE_REDIS_CONNECTION,
+      connectionString ? { connectionString } : void 0
+    );
+  } catch (error) {
+    (_b = (_a = app.log) == null ? void 0 : _a.debug) == null ? void 0 : _b.call(
+      _a,
+      `[plugin-build-guide-block] Redis queue unavailable; DB polling fallback active: ${(error == null ? void 0 : error.message) || error}`
+    );
+    return null;
+  }
+}
+async function enqueueBuildToRedis(app, message) {
+  var _a, _b, _c, _d;
+  const redis = await getBuildQueueRedis(app);
+  if (!redis) return false;
+  try {
+    await redis.sendCommand(["RPUSH", getBuildQueueRedisKey(app), JSON.stringify(message)]);
+    (_b = (_a = app.log) == null ? void 0 : _a.debug) == null ? void 0 : _b.call(
+      _a,
+      `[plugin-build-guide-block] Enqueued build ${message.runId} for space "${message.spaceId}" to Redis`
+    );
+    return true;
+  } catch (error) {
+    (_d = (_c = app.log) == null ? void 0 : _c.warn) == null ? void 0 : _d.call(_c, `[plugin-build-guide-block] Failed to enqueue build to Redis; DB polling fallback active`, error);
+    return false;
+  }
+}
+async function publishBuildQueueWake(app, message) {
+  var _a, _b, _c, _d;
+  try {
+    await ((_b = (_a = app.pubSubManager) == null ? void 0 : _a.publish) == null ? void 0 : _b.call(
+      _a,
+      BUILD_GUIDE_QUEUE_WAKE_CHANNEL,
+      { spaceId: message == null ? void 0 : message.spaceId, runId: message == null ? void 0 : message.runId },
+      { skipSelf: !isBuildGuideWorker(app) }
+    ));
+  } catch (error) {
+    (_d = (_c = app.log) == null ? void 0 : _c.debug) == null ? void 0 : _d.call(_c, `[plugin-build-guide-block] Wake publish skipped: ${(error == null ? void 0 : error.message) || error}`);
+  }
+}
+function startBuildGuideQueueProcessor(app) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  if (!isBuildGuideWorker(app)) {
+    (_b = (_a = app.log) == null ? void 0 : _a.debug) == null ? void 0 : _b.call(_a, "[plugin-build-guide-block] Build queue processor disabled on non-worker node");
+    return;
+  }
+  if (buildQueueTimer) return;
+  buildQueueWakeHandler = async () => {
+    scheduleBuildQueueTick(app, 0);
+  };
+  const subscribe = (_d = (_c = app.pubSubManager) == null ? void 0 : _c.subscribe) == null ? void 0 : _d.call(_c, BUILD_GUIDE_QUEUE_WAKE_CHANNEL, buildQueueWakeHandler);
+  if (subscribe == null ? void 0 : subscribe.catch) {
+    subscribe.catch((error) => {
+      var _a2, _b2;
+      (_b2 = (_a2 = app.log) == null ? void 0 : _a2.debug) == null ? void 0 : _b2.call(_a2, `[plugin-build-guide-block] Wake subscribe skipped: ${(error == null ? void 0 : error.message) || error}`);
+    });
+  }
+  buildQueueTimer = setInterval(() => scheduleBuildQueueTick(app, 0), BUILD_GUIDE_QUEUE_POLL_INTERVAL_MS);
+  (_e = buildQueueTimer.unref) == null ? void 0 : _e.call(buildQueueTimer);
+  scheduleBuildQueueTick(app, 1e3);
+  (_g = (_f = app.log) == null ? void 0 : _f.info) == null ? void 0 : _g.call(
+    _f,
+    `[plugin-build-guide-block] Build queue processor started (interval ${BUILD_GUIDE_QUEUE_POLL_INTERVAL_MS}ms)`
+  );
+}
+function stopBuildGuideQueueProcessor(app) {
+  var _a, _b;
+  if (buildQueueTimer) {
+    clearInterval(buildQueueTimer);
+    buildQueueTimer = null;
+  }
+  if (buildQueueKickTimer) {
+    clearTimeout(buildQueueKickTimer);
+    buildQueueKickTimer = null;
+  }
+  if (buildQueueWakeHandler) {
+    const unsubscribe = (_b = (_a = app.pubSubManager) == null ? void 0 : _a.unsubscribe) == null ? void 0 : _b.call(
+      _a,
+      BUILD_GUIDE_QUEUE_WAKE_CHANNEL,
+      buildQueueWakeHandler
+    );
+    if (unsubscribe == null ? void 0 : unsubscribe.catch) {
+      unsubscribe.catch(() => void 0);
+    }
+    buildQueueWakeHandler = null;
+  }
+  buildQueueProcessing = false;
+}
+function scheduleBuildQueueTick(app, delayMs) {
+  var _a;
+  if (buildQueueKickTimer) return;
+  buildQueueKickTimer = setTimeout(() => {
+    buildQueueKickTimer = null;
+    runBuildQueueTick(app).catch((error) => {
+      var _a2, _b;
+      (_b = (_a2 = app.log) == null ? void 0 : _a2.error) == null ? void 0 : _b.call(_a2, "[plugin-build-guide-block] Build queue tick failed", error);
+    });
+  }, delayMs);
+  (_a = buildQueueKickTimer.unref) == null ? void 0 : _a.call(buildQueueKickTimer);
+}
+async function runBuildQueueTick(app) {
+  if (buildQueueProcessing || !isBuildGuideWorker(app)) return;
+  buildQueueProcessing = true;
+  try {
+    const redisMessages = await drainRedisBuildQueue(app, BUILD_GUIDE_QUEUE_CONCURRENCY);
+    await processBuildQueueMessages(app, redisMessages);
+    const remaining = Math.max(1, BUILD_GUIDE_QUEUE_CONCURRENCY - redisMessages.length);
+    await processQueuedBuildsFromDb(app, remaining);
+  } finally {
+    buildQueueProcessing = false;
+  }
+}
+async function drainRedisBuildQueue(app, count) {
+  var _a, _b;
+  const redis = await getBuildQueueRedis(app);
+  if (!redis) return [];
+  const key = getBuildQueueRedisKey(app);
+  const messages = [];
+  for (let i = 0; i < count; i += 1) {
+    const raw = await redis.sendCommand(["LPOP", key]);
+    if (!raw) break;
+    try {
+      messages.push(JSON.parse(String(raw)));
+    } catch (error) {
+      (_b = (_a = app.log) == null ? void 0 : _a.warn) == null ? void 0 : _b.call(_a, `[plugin-build-guide-block] Dropped invalid Redis build message: ${(error == null ? void 0 : error.message) || error}`);
+    }
+  }
+  return messages;
+}
+function createBuildQueueMessageFromSpace(space) {
+  const runId = space.get("buildRunId");
+  if (!runId) return null;
+  return {
+    spaceId: String(space.get("id")),
+    runId: String(runId),
+    queuedAt: space.get("buildQueuedAt") ? new Date(space.get("buildQueuedAt")).toISOString() : void 0
+  };
+}
+async function processQueuedBuildsFromDb(app, count) {
+  const spaceRepo = app.db.getRepository("aiBuildGuideSpaces");
+  const spaces = await spaceRepo.find({
+    filter: {
+      status: "building",
+      buildPhase: "queued"
+    },
+    sort: ["buildQueuedAt"],
+    limit: count
+  });
+  const messages = spaces.map(createBuildQueueMessageFromSpace).filter(Boolean);
+  await processBuildQueueMessages(app, messages);
+}
+async function processBuildQueueMessages(app, messages) {
+  if (!messages.length) return;
+  await Promise.all(messages.map((message) => processQueuedBuild(app, message)));
+}
+async function markBuildError(app, spaceId, runId, error) {
+  const buildLog = (error == null ? void 0 : error.message) || String(error);
+  let updated = false;
+  if (runId) {
+    updated = await updateSpaceForRun(
+      app,
+      { spaceId, runId },
+      {
+        status: "error",
+        buildPhase: "error",
+        buildLog,
+        buildHeartbeatAt: /* @__PURE__ */ new Date()
+      },
+      true
+    );
+  } else {
+    await app.db.getRepository("aiBuildGuideSpaces").update({
+      filterByTk: spaceId,
+      values: {
+        status: "error",
+        buildPhase: "error",
+        buildLog
+      }
+    });
+    updated = true;
+  }
+  if (!updated) {
+    return;
+  }
+  await app.db.getRepository("aiBuildGuidePages").update({
+    filter: {
+      spaceId,
+      status: "building"
+    },
     values: {
-      status: "completed",
-      buildPhase: "completed",
-      buildLog: `Built ${completedPages.length} chapters successfully`,
-      generatedMarkdown: combinedMarkdown,
-      generatedHtml: combinedHtml
+      status: "error",
+      buildLog
+    }
+  });
+}
+async function enqueueBuild(app, message) {
+  var _a, _b;
+  try {
+    const queuedInRedis = await enqueueBuildToRedis(app, message);
+    if (queuedInRedis) {
+      await publishBuildQueueWake(app, message);
+      return;
+    }
+    await publishBuildQueueWake(app, message);
+    if (isBuildGuideWorker(app)) {
+      await app.eventQueue.publish(BUILD_GUIDE_QUEUE_CHANNEL, message, {
+        timeout: BUILD_GUIDE_QUEUE_TIMEOUT_MS,
+        maxRetries: 0
+      });
+      return;
+    }
+    (_b = (_a = app.log) == null ? void 0 : _a.warn) == null ? void 0 : _b.call(
+      _a,
+      `[plugin-build-guide-block] Redis queue is unavailable; build ${message.runId} for space "${message.spaceId}" will remain queued until a worker DB poller picks it up`
+    );
+  } catch (error) {
+    await markBuildError(app, message.spaceId, message.runId, error);
+    throw error;
+  }
+}
+async function processQueuedBuild(app, message) {
+  var _a, _b;
+  const spaceId = message == null ? void 0 : message.spaceId;
+  const runId = message == null ? void 0 : message.runId;
+  if (!spaceId || !runId) {
+    (_b = (_a = app.log) == null ? void 0 : _a.warn) == null ? void 0 : _b.call(_a, "[plugin-build-guide-block] Build queue message missing spaceId or runId");
+    return;
+  }
+  await withBuildRunLock(app, spaceId, async () => {
+    var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j;
+    const run = { spaceId, runId };
+    const workerId = getBuildWorkerId(app);
+    const claimed = await claimBuildRun(app, run, workerId);
+    if (!claimed) {
+      (_b2 = (_a2 = app.log) == null ? void 0 : _a2.info) == null ? void 0 : _b2.call(_a2, `[plugin-build-guide-block] Build ${runId} for space "${spaceId}" was already claimed or stale`);
+      return;
+    }
+    const spaceRepo = app.db.getRepository("aiBuildGuideSpaces");
+    const space = await spaceRepo.findById(spaceId);
+    if (!space) {
+      (_d = (_c = app.log) == null ? void 0 : _c.warn) == null ? void 0 : _d.call(_c, `[plugin-build-guide-block] Build space "${spaceId}" not found; skipping queued build`);
+      return;
+    }
+    if (space.get("status") !== "building") {
+      (_f = (_e = app.log) == null ? void 0 : _e.info) == null ? void 0 : _f.call(
+        _e,
+        `[plugin-build-guide-block] Build space "${spaceId}" is ${space.get("status")}; skipping queued build`
+      );
+      return;
+    }
+    const stopHeartbeat = startBuildHeartbeat(app, run);
+    try {
+      await runBuild(app, app.db, run);
+    } catch (error) {
+      if (error instanceof StaleBuildRunError) {
+        (_h = (_g = app.log) == null ? void 0 : _g.info) == null ? void 0 : _h.call(_g, `[plugin-build-guide-block] ${error.message}`);
+        return;
+      }
+      (_j = (_i = app.log) == null ? void 0 : _i.error) == null ? void 0 : _j.call(_i, "Build Guide Worker Error", error);
+      await markBuildError(app, spaceId, runId, error);
+    } finally {
+      stopHeartbeat();
+    }
+  });
+}
+function registerBuildGuideQueue(app) {
+  app.eventQueue.subscribe(BUILD_GUIDE_QUEUE_CHANNEL, {
+    concurrency: BUILD_GUIDE_QUEUE_CONCURRENCY,
+    idle: () => isBuildGuideWorker(app),
+    process: async (message) => {
+      await processQueuedBuild(app, message);
     }
   });
+  if (!isBuildGuideWorker(app)) {
+    app.on("afterStart", () => clearLocalBuildMemoryQueue(app));
+  }
+  startBuildGuideQueueProcessor(app);
+}
+function unregisterBuildGuideQueue(app) {
+  app.eventQueue.unsubscribe(BUILD_GUIDE_QUEUE_CHANNEL);
+  stopBuildGuideQueueProcessor(app);
+}
+async function withBuildTriggerLock(app, spaceId, fn) {
+  return app.lockManager.runExclusive(`build-guide:trigger:${spaceId}`, fn, BUILD_TRIGGER_LOCK_TTL_MS);
+}
+async function withBuildRunLock(app, spaceId, fn) {
+  return app.lockManager.runExclusive(`build-guide:run:${spaceId}`, fn, BUILD_RUN_LOCK_TTL_MS);
+}
+async function recoverInterruptedBuilds(app) {
+  var _a, _b;
+  const spaceRepo = app.db.getRepository("aiBuildGuideSpaces");
+  const pageRepo = app.db.getRepository("aiBuildGuidePages");
+  const staleBefore = new Date(Date.now() - BUILD_STALE_MS);
+  const spaces = await spaceRepo.find({
+    filter: {
+      status: "building",
+      $or: [{ buildHeartbeatAt: null }, { buildHeartbeatAt: { $lt: staleBefore } }]
+    }
+  });
+  for (const space of spaces) {
+    const spaceId = String(space.get("id"));
+    const runId = String(space.get("buildRunId") || import_crypto.default.randomUUID());
+    const SpaceModel = getSpaceModel(app);
+    const [affected] = await SpaceModel.update(
+      {
+        buildPhase: "queued",
+        buildLog: "Build re-queued after worker restart",
+        buildRunId: runId,
+        buildQueuedAt: /* @__PURE__ */ new Date(),
+        buildStartedAt: null,
+        buildHeartbeatAt: null,
+        buildWorkerId: null
+      },
+      {
+        where: {
+          id: spaceId,
+          status: "building",
+          buildRunId: space.get("buildRunId") || null
+        }
+      }
+    );
+    if (!affected) {
+      continue;
+    }
+    await pageRepo.update({
+      filter: {
+        spaceId,
+        status: "building"
+      },
+      values: {
+        status: "pending",
+        buildLog: "Build re-queued after worker restart"
+      }
+    });
+    await enqueueBuild(app, {
+      spaceId,
+      runId,
+      queuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  if (spaces.length) {
+    (_b = (_a = app.log) == null ? void 0 : _a.info) == null ? void 0 : _b.call(_a, `[plugin-build-guide-block] Re-queued ${spaces.length} interrupted build(s)`);
+  }
 }
 async function build(ctx, next) {
   const { filterByTk } = ctx.action.params;
-  const repository = ctx.db.getRepository("aiBuildGuideSpaces");
-  const space = await repository.findById(filterByTk);
-  if (!space) {
-    ctx.throw(404, "Space not found");
-  }
-  if (space.get("status") === "building") {
-    ctx.throw(409, "A build is already in progress for this space");
+  if (!filterByTk) {
+    ctx.throw(400, "Space id is required");
   }
   const app = ctx.app;
-  const db = ctx.db;
-  try {
+  const repository = ctx.db.getRepository("aiBuildGuideSpaces");
+  const body = await withBuildTriggerLock(app, String(filterByTk), async () => {
+    var _a, _b;
+    const runId = import_crypto.default.randomUUID();
+    const space = await repository.findById(filterByTk);
+    if (!space) {
+      ctx.throw(404, "Space not found");
+    }
+    if (space.get("status") === "building") {
+      ctx.throw(409, "A build is already in progress for this space");
+    }
     await repository.update({
       filterByTk,
       values: {
         status: "building",
         buildPhase: "queued",
-        buildLog: "Build queued"
+        buildLog: "Build queued",
+        buildRunId: runId,
+        buildQueuedAt: /* @__PURE__ */ new Date(),
+        buildStartedAt: null,
+        buildHeartbeatAt: null,
+        buildWorkerId: null
       }
     });
-    runBuild(app, db, filterByTk).catch(async (error) => {
-      app.log.error("Build Guide Background Error", error);
-      try {
-        await repository.update({
-          filterByTk,
-          values: {
-            status: "error",
-            buildPhase: "error",
-            buildLog: error.message || String(error)
-          }
-        });
-      } catch (updateErr) {
-        app.log.error("Failed to persist build error status", updateErr);
-      }
+    await enqueueBuild(app, {
+      spaceId: String(filterByTk),
+      runId,
+      userId: ((_b = (_a = ctx.state) == null ? void 0 : _a.currentUser) == null ? void 0 : _b.id) ?? null,
+      queuedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
-    ctx.body = { status: "building" };
-  } catch (error) {
-    app.log.error("Build Guide Error", error);
-    await repository.update({
-      filterByTk,
-      values: {
-        status: "error",
-        buildPhase: "error",
-        buildLog: error.message || String(error)
-      }
-    });
-    ctx.throw(500, error.message || "Error occurred during build");
-  }
+    return { status: "building" };
+  });
+  ctx.body = body;
   await next();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  build
+  WORKER_JOB_BUILD_GUIDE_PROCESS,
+  build,
+  recoverInterruptedBuilds,
+  registerBuildGuideQueue,
+  unregisterBuildGuideQueue
 });