@programinglive/dev-workflow-mcp-server 1.10.0 → 1.11.0

package/factory-client.js

@@ -20,8 +20,10 @@
  * above can be tested without a live Factory.
  */
 
-import { createHash } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import os from "os";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
 
 export const DEFAULT_POCKETBASE_URL = "https://pocketbase.programinglive.com";
 
@@ -89,6 +91,11 @@ export function readFactoryConfig(env = process.env) {
     pocketBaseUrl: trimSlash(clean(env.FACTORY_PB_URL) || DEFAULT_POCKETBASE_URL),
     machineId: clean(env.FACTORY_MACHINE_ID),
     deviceId: clean(env.FACTORY_DEVICE_ID),
+    // Berkas identitas perangkat yang dipakai bersama dengan CLI Factory.
+    // Tanpa ini satu mesin muncul sebagai dua perangkat di papan. Bawaannya
+    // jalur yang sama dengan CLI, jadi kedua tool langsung sepakat tanpa
+    // konfigurasi tambahan.
+    deviceFile: clean(env.FACTORY_DEVICE_FILE) || defaultDeviceFile(),
     agent: clean(env.FACTORY_AGENT) || "dev-workflow-mcp",
     // Sesi editor yang sedang berjalan. Papan Factory memakainya untuk
     // menunjukkan sesi mana yang mengerjakan, bukan hanya perangkatnya.
@@ -126,11 +133,59 @@ export function deviceIdFor(seed) {
   ].join("-");
 }
 
+/**
+ * The device identity file the Factory CLI writes.
+ *
+ * Keeping this in one place means the CLI and the MCP server cannot drift to
+ * different paths, which is what made one machine appear as two devices.
+ */
+export function defaultDeviceFile(env = process.env) {
+  return clean(env.FACTORY_DEVICE_FILE) || path.join(os.homedir(), ".config", "programinglive-factory", "device.json");
+}
+
+/**
+ * Reads the device id this machine shares with the Factory CLI.
+ *
+ * The CLI stores a random UUID in `~/.config/programinglive-factory/device.json`.
+ * The MCP server used to derive its own id from the machine name, so one
+ * machine appeared as two devices on the board and a task held by the other
+ * tool looked like another machine's work. Reading and creating the same file
+ * keeps one machine to one identity, whichever tool runs first.
+ *
+ * Returns null when the file cannot be used, so the caller falls back to the
+ * name-derived id instead of failing to claim at all.
+ */
+export function sharedDeviceId(deviceFile) {
+  if (!deviceFile) return null;
+  try {
+    const id = JSON.parse(readFileSync(deviceFile, "utf8"))?.id;
+    if (typeof id === "string" && UUID_RE.test(id)) return id;
+  } catch {
+    // Berkas belum ada atau rusak: dibuat di bawah.
+  }
+
+  const id = randomUUID();
+  try {
+    mkdirSync(path.dirname(deviceFile), { recursive: true, mode: 0o700 });
+    // "wx" gagal kalau proses lain menang balapan; id itu yang dipakai.
+    writeFileSync(deviceFile, JSON.stringify({ id }), { flag: "wx", mode: 0o600 });
+    return id;
+  } catch {
+    try {
+      const existing = JSON.parse(readFileSync(deviceFile, "utf8"))?.id;
+      if (typeof existing === "string" && UUID_RE.test(existing)) return existing;
+    } catch {
+      // Tetap gagal: biar pemanggil memakai id turunan nama mesin.
+    }
+    return null;
+  }
+}
+
 /** Builds the `device` object Factory expects on every work call. */
 export function deviceFromConfig(config) {
   const name = (config.machineId || os.hostname() || "unknown").slice(0, 100);
   return {
-    id: config.deviceId || deviceIdFor(name),
+    id: config.deviceId || sharedDeviceId(config.deviceFile) || deviceIdFor(name),
     name,
     platform: String(process.platform).slice(0, 60),
     agent: String(config.agent || "dev-workflow-mcp").slice(0, 40),
@@ -420,6 +475,33 @@ export async function claimTask(config, { recordId, device, step, takeoverReason
     clientSession: clientSessionFromConfig(config),
   });
   const body = await request(config, "/api/work", { method: "POST", body: payload, fetchImpl });
+  const session = body.session || null;
+  if (!session) return null;
+  // Pemanggil perlu tahu kalau ia baru menggeser perangkat lain, supaya bisa
+  // melaporkan pengambil alihan itu, bukan menyebutnya klaim biasa.
+  return { ...session, tookOver: Boolean(body.tookOver), previousHolder: body.previousHolder || null };
+}
+
+/**
+ * Reports that a work session is still alive, and what it is doing.
+ *
+ * Factory marks a session stale after 120 seconds without a report, so a
+ * claimed task that never reports looks abandoned on the board even while the
+ * work continues. `step` is optional: the server keeps the previous value.
+ */
+export async function heartbeatWork(config, { sessionId, deviceId, step, clientSession } = {}, fetchImpl = fetch) {
+  if (!sessionId) throw new Error("sessionId is required to report a heartbeat.");
+  if (!deviceId) throw new Error("deviceId is required to report a heartbeat.");
+
+  const text = typeof step === "string" ? step.trim() : "";
+  const payload = {
+    action: "heartbeat",
+    sessionId,
+    deviceId,
+    ...(text ? { step: text.slice(0, 240) } : {}),
+    ...(clientSession?.id ? { clientSession: { id: String(clientSession.id).slice(0, 120), title: String(clientSession.title || "").slice(0, 200) } } : {}),
+  };
+  const body = await request(config, "/api/work", { method: "POST", body: payload, fetchImpl });
   return body.session || null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "mcpName": "io.github.programinglive/dev-workflow-mcp-server",

package/session-keeper.js

@@ -0,0 +1,72 @@
+/**
+ * Keeps one Factory work session marked alive while this process holds it.
+ *
+ * Factory shows a session as stale after 120 seconds without a report. The MCP
+ * server claims a task once and then goes quiet, so every task it takes looked
+ * abandoned on the board almost immediately - not because the work stopped, but
+ * because nothing reported it.
+ *
+ * The keeper is deliberately bounded: it reports only while this process holds
+ * a session it started, and it stops the moment the session ends or is taken
+ * over. A heartbeat that outlived the claim would lie in the opposite
+ * direction, showing "active" for work nobody is doing.
+ */
+
+import { heartbeatWork } from "./factory-client.js";
+
+/** How often to report. Comfortably inside the server's 120 second window. */
+const DEFAULT_INTERVAL_MS = 60_000;
+
+let active = null;
+
+async function send(options = {}) {
+  if (!active) return null;
+  const { config, sessionId, deviceId, step, fetchImpl } = active;
+  try {
+    return await heartbeatWork(config, { sessionId, deviceId, step }, fetchImpl ?? options.fetchImpl ?? fetch);
+  } catch (error) {
+    // 409 means the session ended or another device took it over. Retrying
+    // would fight the new holder, so stop and let the board show the truth.
+    if (error?.status === 409 || error?.status === 404) stopKeeping();
+    return null;
+  }
+}
+
+/**
+ * Starts reporting for a session this process just opened.
+ *
+ * Replaces any previous session, because one process works on one task at a
+ * time; two timers would report a session nobody is holding any more.
+ */
+export function startKeeping(config, session, step, options = {}) {
+  stopKeeping();
+  const sessionId = session?.id;
+  const deviceId = session?.device?.id;
+  if (!sessionId || !deviceId) return null;
+
+  const intervalMs = Number.isFinite(options.intervalMs) && options.intervalMs > 0 ? options.intervalMs : DEFAULT_INTERVAL_MS;
+  active = { config, sessionId, deviceId, step: typeof step === "string" ? step : "", fetchImpl: options.fetchImpl, timer: null };
+
+  const timer = setInterval(() => { void send(); }, intervalMs);
+  // Never hold the process open just to report; the session outliving the
+  // process is exactly what "stale" is for.
+  timer.unref?.();
+  active.timer = timer;
+  return { sessionId, deviceId };
+}
+
+/** Stops reporting. Safe to call when nothing is active. */
+export function stopKeeping() {
+  if (active?.timer) clearInterval(active.timer);
+  active = null;
+}
+
+/** The session this process is currently reporting, or null. */
+export function currentSession() {
+  return active ? { sessionId: active.sessionId, deviceId: active.deviceId, step: active.step } : null;
+}
+
+/** Sends one report immediately. Used by tests and after a step change. */
+export async function beatOnce(options = {}) {
+  return send(options);
+}

package/tools/handler-modules/factory-handlers.js

@@ -1,4 +1,5 @@
 import { textResponse } from "./shared.js";
+import { startKeeping, stopKeeping } from "../../session-keeper.js";
 import {
   readFactoryConfig,
   listTasks,
@@ -87,18 +88,19 @@ function formatLastSeen(value) {
  */
 function takeoverRequiredMessage(title, holder = {}) {
   const seen = formatLastSeen(holder.lastSeenAt);
-  const holderText = [holder.deviceName, holder.agent].filter(Boolean).join(" (") + (holder.agent ? ")" : "");
+  const name = String(holder.deviceName || "").trim();
+  const agent = String(holder.agent || "").trim();
+  const holderText = name && agent ? `${name} (${agent})` : name || agent;
   return [
-    `"${title}" sedang dikerjakan oleh perangkat lain.`,
+    `"${title}" is being worked on by another device.`,
+    holderText ? `Holder: ${holderText}${seen ? `, last seen ${seen}` : ""}.` : "",
     "",
-    holderText ? `Pemegang sesi: ${holderText}${seen ? `, terakhir terlihat ${seen}` : ""}.` : "",
+    "To take it over, call claim_factory_task again with a takeoverReason of 3-500 characters:",
+    '  claim_factory_task { "recordId": "<id>", "step": "<step>", "takeoverReason": "<why you are taking over>" }',
     "",
-    "Ambil alih dengan menyertakan alasan (3-500 karakter):",
-    `  claim_factory_task { "recordId": "<id>", "step": "<langkah>", "takeoverReason": "<alasanmu>" }`,
-    "",
-    "Alasannya dicatat di papan, jadi orang berikutnya tahu kenapa pekerjaan berpindah tangan.",
+    "The reason is stored on the board so the next person knows why the work changed hands.",
   ]
-    .filter((line) => line !== "")
+    .filter((line) => line !== null && line !== undefined)
     .join("\n");
 }
 
@@ -127,6 +129,10 @@ export async function handleClaimFactoryTask(args = {}, { workflowState } = {})
     const session = await claimTask(config, { recordId, step, takeoverReason });
     if (!session) throw new Error("Factory accepted the claim but returned no work session.");
 
+    // Tanpa ini sesi jadi "tidak ada kabar" dalam 120 detik padahal sedang
+    // dikerjakan, dan papan terlihat penuh task mati.
+    startKeeping(config, session, step);
+
     if (workflowState) {
       workflowState.reset();
       workflowState.state.currentPhase = "coding";
@@ -138,6 +144,9 @@ export async function handleClaimFactoryTask(args = {}, { workflowState } = {})
     return textResponse(
       [
         `Claimed [${task.taskKey || task.id}] ${task.title}`,
+        session.tookOver && session.previousHolder
+          ? `Took over from ${session.previousHolder.deviceName} (${session.previousHolder.agent}). The reason is recorded on the board.`
+          : "",
         `Factory status is now running (work session ${session.id}).`,
         task.projectName ? `Project: ${task.projectName}` : "",
         "",
@@ -186,6 +195,9 @@ export async function handleSyncTaskStatus(args = {}) {
 
   try {
     const result = await updateTaskStatus(config, { recordId, status, reason, nextAction });
+    // Sesi ditutup, jadi berhenti melaporkan: heartbeat setelah ini akan
+    // ditolak server dan hanya mengaburkan keadaan papan.
+    stopKeeping();
 
     return textResponse(
       [