kanbango 3.5.0 → 3.6.2

package/workflow.js

@@ -0,0 +1,460 @@
+const fs = require('fs').promises;
+const path = require('path');
+const { spawn } = require('child_process');
+const kanban = require('./kanban.js');
+
+const BACKLOG = path.join(process.cwd(), 'backlog');
+const CONFIG_PATH = path.join(BACKLOG, 'kanbango.json');
+const JOBS_DIR = path.join(BACKLOG, '.workflow');
+
+/** PIDs spawned by this process — only these may be SIGTERM'd on timeout. */
+const ownedPids = new Set();
+/** In-flight run_ids to prevent double-spawn within this process. */
+const runningLocal = new Set();
+
+function workflowError(code, message, hint, details = {}) {
+  return kanban.createKanbanError(code, message, hint, details, false, 400);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function assertWorkflowShape(workflow) {
+  if (!workflow || typeof workflow !== 'object' || Array.isArray(workflow)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow config must be an object',
+      'Set backlog/kanbango.json with a workflow object',
+      { field: 'workflow' }
+    );
+  }
+  if (typeof workflow.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow.enabled must be a boolean',
+      'Use "enabled": true or false',
+      { field: 'workflow.enabled' }
+    );
+  }
+  const stringFields = ['command', 'testing_agent', 'e2e_agent', 'review_agent'];
+  for (const field of stringFields) {
+    if (workflow[field] !== undefined && !isNonEmptyString(workflow[field])) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        `workflow.${field} must be a non-empty string when set`,
+        `Fix workflow.${field} in backlog/kanbango.json`,
+        { field: `workflow.${field}` }
+      );
+    }
+  }
+  if (workflow.timeout_ms !== undefined) {
+    if (!Number.isInteger(workflow.timeout_ms) || workflow.timeout_ms <= 0) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        'workflow.timeout_ms must be a positive integer',
+        'Use milliseconds, e.g. 600000',
+        { field: 'workflow.timeout_ms' }
+      );
+    }
+  }
+}
+
+async function loadConfig() {
+  let raw;
+  try {
+    raw = await fs.readFile(CONFIG_PATH, 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { enabled: false, missing: true };
+    }
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'backlog/kanbango.json is not valid JSON',
+      'Fix JSON syntax or remove the file to disable workflow',
+      { reason: error.message }
+    );
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'kanbango.json root must be an object',
+      'Use { "workflow": { ... } }',
+      { field: 'root' }
+    );
+  }
+
+  assertWorkflowShape(parsed.workflow);
+  const w = parsed.workflow;
+  const envRunner = String(process.env.KANBANGO_WORKFLOW_RUNNER || '').trim();
+
+  return {
+    enabled: w.enabled,
+    missing: false,
+    command: envRunner || (isNonEmptyString(w.command) ? w.command.trim() : 'opencode'),
+    testing_agent: isNonEmptyString(w.testing_agent) ? w.testing_agent.trim() : 'qa-tester',
+    e2e_agent: isNonEmptyString(w.e2e_agent) ? w.e2e_agent.trim() : 'qa-e2e-tester',
+    review_agent: isNonEmptyString(w.review_agent) ? w.review_agent.trim() : 'temida',
+    timeout_ms: Number.isInteger(w.timeout_ms) && w.timeout_ms > 0 ? w.timeout_ms : 600000
+  };
+}
+
+function newRunId() {
+  return `run-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+}
+
+function agentForStage(config, stage) {
+  if (stage === 'review') return config.review_agent;
+  return config.testing_agent;
+}
+
+function buildPrompt(taskId, stage, agent) {
+  const lines = [
+    `Kanbango workflow stage=${stage} agent=${agent} task_id=${taskId}.`,
+    `Read the kanbango task ${taskId} (kanban_read show view=execution).`,
+    'Perform your agent role.'
+  ];
+  if (stage === 'testing') {
+    lines.push('Write/run tests only. End with a clear verdict line: PASS or FAIL or BLOCKED.');
+  }
+  if (stage === 'review') {
+    lines.push('After your verdict, the LAST line of the response MUST be exactly GATE: PASS or GATE: FAIL.');
+  }
+  return lines.join(' ');
+}
+
+function truncate(text, max = 2000) {
+  const s = String(text || '');
+  if (s.length <= max) return s;
+  return s.slice(s.length - max);
+}
+
+function parseTestingVerdict(stdout, stderr, exitCode) {
+  const text = `${stdout}\n${stderr}`;
+  if (/\bBLOCKED\b/i.test(text)) return 'blocked';
+  if (/\bPASS\b/i.test(text) && !/\bFAIL\b/i.test(text)) return 'pass';
+  if (/\bFAIL\b/i.test(text)) return 'fail';
+  if (exitCode !== 0) return 'fail';
+  return 'fail';
+}
+
+function parseReviewGate(stdout, stderr) {
+  const lines = `${stdout}\n${stderr}`
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const last = lines[lines.length - 1] || '';
+  if (last === 'GATE: PASS') return 'pass';
+  if (last === 'GATE: FAIL') return 'fail';
+  return null;
+}
+
+async function writeJob(job) {
+  await fs.mkdir(JOBS_DIR, { recursive: true });
+  const filePath = path.join(JOBS_DIR, `${job.run_id}.json`);
+  await fs.writeFile(filePath, JSON.stringify(job, null, 2) + '\n', 'utf-8');
+  return filePath;
+}
+
+async function updateJob(runId, patch) {
+  const filePath = path.join(JOBS_DIR, `${runId}.json`);
+  let job = {};
+  try {
+    job = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+  } catch {
+    job = { run_id: runId };
+  }
+  const next = { ...job, ...patch };
+  await fs.writeFile(filePath, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+  return next;
+}
+
+function spawnRunner(config, prompt, agent) {
+  return new Promise((resolve) => {
+    const args = ['run', prompt, '--agent', agent, '--format', 'json', '--dir', process.cwd()];
+    let child;
+    try {
+      child = spawn(config.command, args, {
+        cwd: process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        env: process.env
+      });
+    } catch (error) {
+      resolve({
+        stdout: '',
+        stderr: error.message || String(error),
+        exitCode: 1,
+        timedOut: false,
+        pid: null,
+        argv: [config.command, ...args]
+      });
+      return;
+    }
+
+    const pid = child.pid;
+    if (pid) ownedPids.add(pid);
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      if (pid && ownedPids.has(pid)) {
+        try {
+          child.kill('SIGTERM');
+        } catch (killErr) {
+          // process may have already exited
+          if (killErr && killErr.code !== 'ESRCH') {
+            stderr += `\nkill failed: ${killErr.message || killErr}`;
+          }
+        }
+      }
+    }, config.timeout_ms);
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    const finish = (exitCode) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (pid) ownedPids.delete(pid);
+      resolve({
+        stdout,
+        stderr,
+        exitCode: exitCode == null ? 1 : exitCode,
+        timedOut,
+        pid,
+        argv: [config.command, ...args]
+      });
+    };
+
+    child.on('error', (error) => {
+      stderr += error.message || String(error);
+      finish(1);
+    });
+    child.on('close', (code) => finish(code));
+  });
+}
+
+function outcomeForResult(stage, result) {
+  if (result.timedOut) {
+    return {
+      verdict: 'blocked',
+      nextColumn: null,
+      workflowStatus: 'blocked',
+      summary: `timeout after runner; card stays in ${stage}`
+    };
+  }
+
+  if (stage === 'testing') {
+    const verdict = parseTestingVerdict(result.stdout, result.stderr, result.exitCode);
+    if (verdict === 'pass') {
+      return {
+        verdict: 'pass',
+        nextColumn: 'review',
+        workflowStatus: 'pass',
+        summary: truncate(result.stdout || 'PASS', 500)
+      };
+    }
+    if (verdict === 'blocked') {
+      return {
+        verdict: 'blocked',
+        nextColumn: 'active',
+        workflowStatus: 'blocked',
+        summary: truncate(result.stdout || result.stderr || 'BLOCKED', 500)
+      };
+    }
+    return {
+      verdict: 'fail',
+      nextColumn: 'active',
+      workflowStatus: 'fail',
+      summary: truncate(result.stdout || result.stderr || 'FAIL', 500)
+    };
+  }
+
+  // review
+  const gate = parseReviewGate(result.stdout, result.stderr);
+  if (gate === 'pass') {
+    return {
+      verdict: 'pass',
+      nextColumn: 'done',
+      workflowStatus: 'pass',
+      summary: 'GATE: PASS'
+    };
+  }
+  if (gate === 'fail') {
+    return {
+      verdict: 'fail',
+      nextColumn: 'active',
+      workflowStatus: 'fail',
+      summary: 'GATE: FAIL'
+    };
+  }
+  return {
+    verdict: 'blocked',
+    nextColumn: null,
+    workflowStatus: 'blocked',
+    summary: truncate(result.stdout || result.stderr || 'missing GATE marker', 500)
+  };
+}
+
+async function finishRun(taskId, stage, agent, runId, result) {
+  const outcome = outcomeForResult(stage, result);
+  const finishedAt = new Date().toISOString();
+  const evidence = {
+    diff: '',
+    test_command: (result.argv || []).join(' '),
+    stdout: truncate(result.stdout),
+    stderr: truncate(result.stderr),
+    exit_code: result.exitCode,
+    created: finishedAt,
+    stage,
+    agent,
+    verdict: outcome.verdict,
+    summary: outcome.summary
+  };
+
+  const patch = {
+    appendEvidence: evidence,
+    workflow: {
+      stage,
+      status: outcome.workflowStatus,
+      agent,
+      run_id: runId,
+      finished_at: finishedAt
+    }
+  };
+  if (outcome.nextColumn) {
+    patch.column = outcome.nextColumn;
+  }
+
+  await kanban.updateTask(taskId, patch);
+  await updateJob(runId, {
+    status: outcome.workflowStatus,
+    finished_at: finishedAt,
+    verdict: outcome.verdict,
+    exit_code: result.exitCode,
+    timed_out: Boolean(result.timedOut)
+  });
+  runningLocal.delete(runId);
+}
+
+async function startRun(task, stage, config) {
+  const agent = agentForStage(config, stage);
+  const runId = newRunId();
+  const startedAt = new Date().toISOString();
+
+  runningLocal.add(runId);
+
+  await kanban.updateTask(task.id, {
+    workflow: {
+      stage,
+      status: 'running',
+      agent,
+      run_id: runId,
+      started_at: startedAt
+    }
+  });
+
+  await writeJob({
+    run_id: runId,
+    task_id: task.id,
+    stage,
+    agent,
+    started_at: startedAt,
+    status: 'running'
+  });
+
+  // Spawn outside any board lock (caller already released lock).
+  setImmediate(async () => {
+    const prompt = buildPrompt(task.id, stage, agent);
+    const result = await spawnRunner(config, prompt, agent);
+    if (result.pid) {
+      await updateJob(runId, { pid: result.pid });
+    }
+    try {
+      await finishRun(task.id, stage, agent, runId, result);
+    } catch (error) {
+      console.error('workflow finish failed:', error && error.message ? error.message : error);
+      runningLocal.delete(runId);
+    }
+  });
+
+  return { run_id: runId, agent, stage, status: 'running' };
+}
+
+/**
+ * Called after a successful column change into testing|review.
+ * Must not run inside withBoardLock.
+ */
+async function maybeEnqueueOnColumnEnter(task, previousColumn) {
+  if (!task || !kanban.WORKFLOW_STAGES.includes(task.column)) {
+    return { enqueued: false, reason: 'not_gate_column' };
+  }
+  if (previousColumn === task.column) {
+    return { enqueued: false, reason: 'same_column' };
+  }
+
+  const config = await loadConfig();
+  if (config.missing || !config.enabled) {
+    return { enqueued: false, reason: config.missing ? 'no_config' : 'disabled' };
+  }
+
+  // Dedup: already running this stage
+  const wf = task.workflow;
+  if (wf && wf.status === 'running' && wf.stage === task.column) {
+    return { enqueued: false, reason: 'already_running' };
+  }
+  if (wf && wf.run_id && runningLocal.has(wf.run_id) && wf.stage === task.column) {
+    return { enqueued: false, reason: 'already_running_local' };
+  }
+
+  const fresh = await kanban.getTask(task.id);
+  if (fresh.workflow && fresh.workflow.status === 'running' && fresh.workflow.stage === task.column) {
+    return { enqueued: false, reason: 'already_running' };
+  }
+
+  const started = await startRun(fresh, task.column, config);
+  return { enqueued: true, ...started };
+}
+
+/** Test helper: wait until a run reaches a terminal workflow status. */
+async function waitForIdle(taskId, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let sawRunning = false;
+  while (Date.now() < deadline) {
+    const task = await kanban.getTask(taskId);
+    const status = task.workflow && task.workflow.status;
+    if (status === 'running') sawRunning = true;
+    if (status === 'pass' || status === 'fail' || status === 'blocked') return task;
+    if (sawRunning && status !== 'running') return task;
+    await new Promise((r) => setTimeout(r, 40));
+  }
+  throw new Error(`waitForIdle timeout for task ${taskId}`);
+}
+
+module.exports = {
+  loadConfig,
+  maybeEnqueueOnColumnEnter,
+  parseTestingVerdict,
+  parseReviewGate,
+  waitForIdle,
+  JOBS_DIR,
+  CONFIG_PATH
+};