@programinglive/dev-workflow-mcp-server 1.10.0 → 1.12.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.12.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(
       [

package/workflow-state.js

@@ -408,6 +408,55 @@ async function ensureCompatibilityLinks(primaryPath) {
   }
 }
 
+/**
+ * Identitas sesi agen ini.
+ *
+ * MENGAPA ADA
+ * -----------
+ * Berkas state dulu disimpan per USER, jadi empat proses MCP berbagi satu
+ * `workflow-state.json`. Akibatnya `start_task` di satu sesi mengganti task
+ * sesi lain di tengah jalan, dan gerbang kualitas (ready check, tests, docs)
+ * ikut dibagi sehingga sesi B bisa memakai hasil sesi A untuk commit.
+ *
+ * Sekarang task dan gerbangnya milik SESI; `history` tetap milik PROYEK.
+ *
+ * Urutannya sengaja: env eksplisit dulu (untuk tes dan pemanggil lain), lalu
+ * id sesi editor, lalu proses. Jatuh ke proses membuat identitas tetap stabil
+ * walau modul di-reload dalam proses yang sama.
+ */
+export function resolveSessionKey(env = process.env) {
+  for (const candidate of [env.DEV_WORKFLOW_SESSION_ID, env.OPENCODE_SESSION_ID, env.CLIENT_SESSION_ID]) {
+    const value = typeof candidate === "string" ? candidate.trim() : "";
+    if (value) return sanitizeSessionKey(value);
+  }
+  return `pid-${process.pid}`;
+}
+
+function sanitizeSessionKey(value) {
+  const cleaned = String(value).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+  return (cleaned || "session").slice(0, 64);
+}
+
+/** Nama berkas state untuk sesi ini, di direktori user yang sama. */
+function sessionStateFilename(env = process.env) {
+  return `workflow-state.${resolveSessionKey(env)}.json`;
+}
+
+/**
+ * Berkas tempat `history` bersama disimpan.
+ *
+ * Dalam tata letak nyata (`.state/users/<user>/`) history dipisahkan dari state
+ * sesi supaya catatan proyek tidak terpecah per sesi. Pemanggil yang memberi
+ * path eksplisit di luar tata letak itu tetap memakai satu berkas, persis
+ * seperti sebelumnya.
+ */
+export function resolveHistoryFile(stateFilePath) {
+  const resolved = path.resolve(stateFilePath);
+  const dir = path.dirname(resolved);
+  const inUserTree = path.basename(path.dirname(dir)) === "users";
+  return inUserTree ? path.join(dir, STATE_FILENAME) : resolved;
+}
+
 export function resolveStateFile() {
   const customPath = process.env.DEV_WORKFLOW_STATE_FILE;
   if (customPath) {
@@ -438,12 +487,15 @@ export function resolveStateFile() {
 
   const stateDir = path.join(projectRoot, STATE_DIR);
   const userDir = getUserScopedDir(stateDir);
-  return path.join(userDir, STATE_FILENAME);
+  return path.join(userDir, sessionStateFilename());
 }
 
 export class WorkflowState {
   constructor(stateFilePath = resolveStateFile()) {
     this.stateFile = stateFilePath;
+    // History milik proyek, state milik sesi. Dalam tata letak nyata keduanya
+    // berkas berbeda; untuk path eksplisit keduanya menunjuk berkas yang sama.
+    this.historyFile = resolveHistoryFile(stateFilePath);
     this.state = {
       currentPhase: "idle",
       taskDescription: "",
@@ -482,6 +534,7 @@ export class WorkflowState {
       // Ensure compatibility mirrors exist whenever the primary file is present
       // Run this as non-blocking to speed up startup
       ensureCompatibilityLinks(this.stateFile).catch(() => { });
+      await this.mergeSharedHistory();
       if (typeof this.state.testsCreated !== "boolean") {
         this.state.testsCreated = false;
       }
@@ -530,9 +583,61 @@ export class WorkflowState {
       }
       // Missing file is fine; bootstrap fresh artifacts for downstream consumers.
       await this.ensurePrimaryFile();
+      // Sesi baru tetap harus melihat riwayat proyek yang sudah ada.
+      await this.mergeSharedHistory();
     }
   }
 
+  /**
+   * Menyatukan `history` sesi ini dengan `history` bersama.
+   *
+   * History adalah catatan proyek: task yang selesai di satu sesi harus
+   * terlihat dari sesi lain, dan entri yang sama tidak boleh berganda walau
+   * berkali-kali disimpan.
+   */
+  async mergeSharedHistory() {
+    if (this.historyFile === this.stateFile) {
+      return 0;
+    }
+
+    const shared = await this.readHistoryFile();
+    const merged = this.mergeDiskHistory(shared);
+    if (merged > 0) {
+      await this.writeHistoryFile();
+    }
+    return merged;
+  }
+
+  async readHistoryFile() {
+    try {
+      const data = await fs.readFile(this.historyFile, "utf-8");
+      return JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Menulis hanya `history` ke berkas bersama, tanpa task milik sesi ini. */
+  async writeHistoryFile() {
+    if (this.historyFile === this.stateFile) {
+      return;
+    }
+
+    const shared = (await this.readHistoryFile()) || {};
+    const merged = Array.isArray(shared.history) ? shared.history.slice() : [];
+    const seen = new Set(merged.map((entry) => this.historyKey(entry)));
+    for (const entry of this.state.history || []) {
+      const key = this.historyKey(entry);
+      if (!seen.has(key)) {
+        merged.push(entry);
+        seen.add(key);
+      }
+    }
+
+    await fs.mkdir(path.dirname(this.historyFile), { recursive: true });
+    await fs.writeFile(this.historyFile, JSON.stringify({ ...shared, history: merged }, null, 2));
+  }
+
   async ensurePrimaryFile() {
     let created = false;
     try {
@@ -558,6 +663,9 @@ export class WorkflowState {
       updatedAt: new Date().toISOString(),
     };
     await fs.writeFile(this.stateFile, JSON.stringify(this.state, null, 2));
+    // History ditulis ke berkas bersama supaya sesi lain melihat task yang
+    // selesai di sini, sementara task yang sedang berjalan tetap milik sesi.
+    await this.writeHistoryFile();
     await ensureCompatibilityLinks(this.stateFile);
     await this.updateProjectSummary();
     await this.syncToDatabase();