kanbango 3.6.2 → 3.8.0

package/workflow.js

@@ -7,11 +7,25 @@ const BACKLOG = path.join(process.cwd(), 'backlog');
 const CONFIG_PATH = path.join(BACKLOG, 'kanbango.json');
 const JOBS_DIR = path.join(BACKLOG, '.workflow');
 
+const GATE_COLUMNS = ['testing', 'review'];
+const DEFAULT_LABELS = {
+  icebox: 'Icebox',
+  planned: 'Planned',
+  active: 'NOW',
+  testing: 'Testing',
+  review: 'Review',
+  done: 'Done'
+};
+
 /** 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();
 
+let cachedConfig = null;
+let cacheCwd = null;
+let ensureTail = Promise.resolve();
+
 function workflowError(code, message, hint, details = {}) {
   return kanban.createKanbanError(code, message, hint, details, false, 400);
 }
@@ -20,6 +34,85 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
+function parseAgentField(value, fieldName, defaultName) {
+  if (value === undefined) {
+    return { enabled: true, name: defaultName };
+  }
+  if (typeof value === 'string') {
+    if (!isNonEmptyString(value)) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        `workflow.${fieldName} must be a non-empty string when set`,
+        `Fix workflow.${fieldName} in backlog/kanbango.json`,
+        { field: `workflow.${fieldName}` }
+      );
+    }
+    return { enabled: true, name: value.trim() };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName} must be a string or { enabled, name }`,
+      `Use a name string or object with optional enabled/name`,
+      { field: `workflow.${fieldName}` }
+    );
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName}.enabled must be a boolean`,
+      'Use true or false',
+      { field: `workflow.${fieldName}.enabled` }
+    );
+  }
+  if (value.name !== undefined && !isNonEmptyString(value.name)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `workflow.${fieldName}.name must be a non-empty string when set`,
+      `Fix workflow.${fieldName}.name in backlog/kanbango.json`,
+      { field: `workflow.${fieldName}.name` }
+    );
+  }
+  return {
+    enabled: value.enabled === undefined ? true : value.enabled,
+    name: isNonEmptyString(value.name) ? value.name.trim() : defaultName
+  };
+}
+
+function parseGateColumn(value, columnId) {
+  if (value === undefined) {
+    return { enabled: true, label: DEFAULT_LABELS[columnId] };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId} must be an object`,
+      `Use { "enabled": true, "label": "${DEFAULT_LABELS[columnId]}" }`,
+      { field: `columns.${columnId}` }
+    );
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId}.enabled must be a boolean`,
+      'Use true or false',
+      { field: `columns.${columnId}.enabled` }
+    );
+  }
+  if (value.label !== undefined && !isNonEmptyString(value.label)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      `columns.${columnId}.label must be a non-empty string when set`,
+      `Fix columns.${columnId}.label in backlog/kanbango.json`,
+      { field: `columns.${columnId}.label` }
+    );
+  }
+  return {
+    enabled: value.enabled === undefined ? true : value.enabled,
+    label: isNonEmptyString(value.label) ? value.label.trim() : DEFAULT_LABELS[columnId]
+  };
+}
+
 function assertWorkflowShape(workflow) {
   if (!workflow || typeof workflow !== 'object' || Array.isArray(workflow)) {
     throw workflowError(
@@ -37,14 +130,23 @@ function assertWorkflowShape(workflow) {
       { field: 'workflow.enabled' }
     );
   }
-  const stringFields = ['command', 'testing_agent', 'e2e_agent', 'review_agent'];
-  for (const field of stringFields) {
-    if (workflow[field] !== undefined && !isNonEmptyString(workflow[field])) {
+  if (workflow.command !== undefined && !isNonEmptyString(workflow.command)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'workflow.command must be a non-empty string when set',
+      'Fix workflow.command in backlog/kanbango.json',
+      { field: 'workflow.command' }
+    );
+  }
+  if (workflow.e2e_agent !== undefined && !isNonEmptyString(workflow.e2e_agent)
+    && !(workflow.e2e_agent && typeof workflow.e2e_agent === 'object')) {
+    // Keep legacy string validation; object form not used for spawn yet.
+    if (typeof workflow.e2e_agent === 'string' && !isNonEmptyString(workflow.e2e_agent)) {
       throw workflowError(
         'CONFIG_INVALID',
-        `workflow.${field} must be a non-empty string when set`,
-        `Fix workflow.${field} in backlog/kanbango.json`,
-        { field: `workflow.${field}` }
+        'workflow.e2e_agent must be a non-empty string when set',
+        'Fix workflow.e2e_agent in backlog/kanbango.json',
+        { field: 'workflow.e2e_agent' }
       );
     }
   }
@@ -58,6 +160,132 @@ function assertWorkflowShape(workflow) {
       );
     }
   }
+  // Validate agent fields early (parseAgentField throws CONFIG_INVALID).
+  parseAgentField(workflow.testing_agent, 'testing_agent', 'qa-tester');
+  parseAgentField(workflow.review_agent, 'review_agent', 'temida');
+  if (workflow.e2e_agent !== undefined && typeof workflow.e2e_agent === 'string') {
+    parseAgentField(workflow.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+  }
+}
+
+function assertColumnsShape(columns) {
+  if (columns === undefined) return;
+  if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
+    throw workflowError(
+      'CONFIG_INVALID',
+      'columns config must be an object',
+      'Use { "testing": { "enabled": true, "label": "Testing" }, "review": { ... } }',
+      { field: 'columns' }
+    );
+  }
+  for (const key of Object.keys(columns)) {
+    if (!GATE_COLUMNS.includes(key)) {
+      throw workflowError(
+        'CONFIG_INVALID',
+        `columns.${key} is not configurable`,
+        'Only testing and review may be set under columns',
+        { field: `columns.${key}`, allowed: GATE_COLUMNS }
+      );
+    }
+  }
+  parseGateColumn(columns.testing, 'testing');
+  parseGateColumn(columns.review, 'review');
+}
+
+function buildTransitions(testingOn, reviewOn) {
+  const afterActive = testingOn ? 'testing' : (reviewOn ? 'review' : 'done');
+  const afterTesting = reviewOn ? 'review' : 'done';
+
+  const transitions = {
+    icebox: ['planned'],
+    planned: ['active', 'icebox', afterActive],
+    active: ['planned', afterActive, 'icebox'],
+    done: ['active']
+  };
+
+  // Dedupe while preserving order
+  for (const key of Object.keys(transitions)) {
+    transitions[key] = [...new Set(transitions[key])];
+  }
+
+  if (testingOn) {
+    transitions.testing = ['active', afterTesting];
+  }
+  if (reviewOn) {
+    transitions.review = ['active', 'done'];
+  }
+
+  return transitions;
+}
+
+function buildActiveCols(testingOn, reviewOn) {
+  const cols = ['active', 'planned', 'icebox'];
+  if (testingOn) cols.push('testing');
+  if (reviewOn) cols.push('review');
+  cols.push('done');
+  return cols;
+}
+
+function planDoneTarget(testingOn, reviewOn) {
+  if (testingOn) return 'testing';
+  if (reviewOn) return 'review';
+  return 'done';
+}
+
+function defaultConfig() {
+  const testingOn = true;
+  const reviewOn = true;
+  return {
+    missing: true,
+    enabled: false,
+    command: 'opencode',
+    testing_agent: { enabled: true, name: 'qa-tester' },
+    e2e_agent: { enabled: true, name: 'qa-e2e-tester' },
+    review_agent: { enabled: true, name: 'temida' },
+    timeout_ms: 600000,
+    columns: {
+      icebox: { enabled: true, label: DEFAULT_LABELS.icebox },
+      planned: { enabled: true, label: DEFAULT_LABELS.planned },
+      active: { enabled: true, label: DEFAULT_LABELS.active },
+      testing: { enabled: true, label: DEFAULT_LABELS.testing },
+      review: { enabled: true, label: DEFAULT_LABELS.review },
+      done: { enabled: true, label: DEFAULT_LABELS.done }
+    },
+    active_cols: buildActiveCols(testingOn, reviewOn),
+    workflow_stages: GATE_COLUMNS.slice(),
+    transitions: buildTransitions(testingOn, reviewOn),
+    plan_done_column: planDoneTarget(testingOn, reviewOn),
+    move_order: ['icebox', 'planned', 'active', 'testing', 'review', 'done'],
+    board_columns: [
+      { id: 'icebox', label: DEFAULT_LABELS.icebox },
+      { id: 'planned', label: DEFAULT_LABELS.planned },
+      { id: 'testing', label: DEFAULT_LABELS.testing },
+      { id: 'review', label: DEFAULT_LABELS.review },
+      { id: 'done', label: DEFAULT_LABELS.done }
+    ]
+  };
+}
+
+function shapePublicConfig(config) {
+  return {
+    columns: config.columns,
+    active_cols: config.active_cols.slice(),
+    workflow_stages: config.workflow_stages.slice(),
+    transitions: Object.fromEntries(
+      Object.entries(config.transitions).map(([k, v]) => [k, v.slice()])
+    ),
+    plan_done_column: config.plan_done_column,
+    move_order: config.move_order.slice(),
+    board_columns: config.board_columns.map((c) => ({ id: c.id, label: c.label })),
+    workflow: {
+      enabled: config.enabled,
+      command: config.command,
+      testing_agent: { ...config.testing_agent },
+      e2e_agent: { ...config.e2e_agent },
+      review_agent: { ...config.review_agent },
+      timeout_ms: config.timeout_ms
+    }
+  };
 }
 
 async function loadConfig() {
@@ -66,7 +294,7 @@ async function loadConfig() {
     raw = await fs.readFile(CONFIG_PATH, 'utf-8');
   } catch (error) {
     if (error.code === 'ENOENT') {
-      return { enabled: false, missing: true };
+      return defaultConfig();
     }
     throw error;
   }
@@ -87,26 +315,121 @@ async function loadConfig() {
     throw workflowError(
       'CONFIG_INVALID',
       'kanbango.json root must be an object',
-      'Use { "workflow": { ... } }',
+      'Use { "workflow": { ... }, "columns": { ... } }',
       { field: 'root' }
     );
   }
 
-  assertWorkflowShape(parsed.workflow);
-  const w = parsed.workflow;
+  assertColumnsShape(parsed.columns);
+
+  // workflow optional when only columns are configured
+  let w = parsed.workflow;
+  if (w === undefined) {
+    w = { enabled: false };
+  }
+  assertWorkflowShape(w);
+
+  const testingCol = parseGateColumn(parsed.columns && parsed.columns.testing, 'testing');
+  const reviewCol = parseGateColumn(parsed.columns && parsed.columns.review, 'review');
+  const testingOn = testingCol.enabled;
+  const reviewOn = reviewCol.enabled;
+
+  const testingAgent = parseAgentField(w.testing_agent, 'testing_agent', 'qa-tester');
+  const reviewAgent = parseAgentField(w.review_agent, 'review_agent', 'temida');
+  let e2eAgent = { enabled: true, name: 'qa-e2e-tester' };
+  if (w.e2e_agent !== undefined) {
+    if (typeof w.e2e_agent === 'string') {
+      e2eAgent = parseAgentField(w.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+    } else {
+      e2eAgent = parseAgentField(w.e2e_agent, 'e2e_agent', 'qa-e2e-tester');
+    }
+  }
+
   const envRunner = String(process.env.KANBANGO_WORKFLOW_RUNNER || '').trim();
+  const activeCols = buildActiveCols(testingOn, reviewOn);
+  const workflowStages = GATE_COLUMNS.filter((col) => (col === 'testing' ? testingOn : reviewOn));
+  const moveOrder = ['icebox', 'planned', 'active']
+    .concat(testingOn ? ['testing'] : [])
+    .concat(reviewOn ? ['review'] : [])
+    .concat(['done']);
+
+  const boardColumns = [
+    { id: 'icebox', label: DEFAULT_LABELS.icebox },
+    { id: 'planned', label: DEFAULT_LABELS.planned }
+  ];
+  if (testingOn) boardColumns.push({ id: 'testing', label: testingCol.label });
+  if (reviewOn) boardColumns.push({ id: 'review', label: reviewCol.label });
+  boardColumns.push({ id: 'done', label: DEFAULT_LABELS.done });
 
   return {
-    enabled: w.enabled,
     missing: false,
+    enabled: w.enabled,
     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
+    testing_agent: testingAgent,
+    e2e_agent: e2eAgent,
+    review_agent: reviewAgent,
+    timeout_ms: Number.isInteger(w.timeout_ms) && w.timeout_ms > 0 ? w.timeout_ms : 600000,
+    columns: {
+      icebox: { enabled: true, label: DEFAULT_LABELS.icebox },
+      planned: { enabled: true, label: DEFAULT_LABELS.planned },
+      active: { enabled: true, label: DEFAULT_LABELS.active },
+      testing: testingCol,
+      review: reviewCol,
+      done: { enabled: true, label: DEFAULT_LABELS.done }
+    },
+    active_cols: activeCols,
+    workflow_stages: workflowStages,
+    transitions: buildTransitions(testingOn, reviewOn),
+    plan_done_column: planDoneTarget(testingOn, reviewOn),
+    move_order: moveOrder,
+    board_columns: boardColumns
   };
 }
 
+async function migrateDisabledGateCards(config) {
+  const migrated = [];
+  for (const col of GATE_COLUMNS) {
+    if (config.columns[col].enabled) continue;
+    const tasks = await kanban.listTasksInKnownColumn(col);
+    for (const task of tasks) {
+      await kanban.relocateTask(task.id, 'planned');
+      migrated.push({ id: task.id, from: col, to: 'planned' });
+    }
+  }
+  return migrated;
+}
+
+/**
+ * Load board config, apply layout to kanban, migrate cards out of disabled gates.
+ * Always re-reads backlog/kanbango.json (file is small) so enable/disable changes apply.
+ * Migration is idempotent: second call finds no cards in disabled columns.
+ */
+async function ensureBoardConfig({ force = false } = {}) {
+  const run = ensureTail.then(async () => {
+    const cwd = process.cwd();
+    // force kept for API/tests; always reload from disk so config edits are live.
+    void force;
+    const config = await loadConfig();
+    kanban.applyBoardLayout({
+      cols: config.active_cols,
+      transitions: config.transitions,
+      workflowStages: config.workflow_stages
+    });
+    await migrateDisabledGateCards(config);
+
+    cachedConfig = config;
+    cacheCwd = cwd;
+    return config;
+  });
+  ensureTail = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+function clearConfigCache() {
+  cachedConfig = null;
+  cacheCwd = null;
+}
+
 function newRunId() {
   return `run-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
 }
@@ -265,9 +588,11 @@ function outcomeForResult(stage, result) {
   if (stage === 'testing') {
     const verdict = parseTestingVerdict(result.stdout, result.stderr, result.exitCode);
     if (verdict === 'pass') {
+      const config = cachedConfig || defaultConfig();
+      const nextColumn = config.columns.review.enabled ? 'review' : 'done';
       return {
         verdict: 'pass',
-        nextColumn: 'review',
+        nextColumn,
         workflowStatus: 'pass',
         summary: truncate(result.stdout || 'PASS', 500)
       };
@@ -356,7 +681,8 @@ async function finishRun(taskId, stage, agent, runId, result) {
 }
 
 async function startRun(task, stage, config) {
-  const agent = agentForStage(config, stage);
+  const agentField = agentForStage(config, stage);
+  const agent = agentField.name;
   const runId = newRunId();
   const startedAt = new Date().toISOString();
 
@@ -411,11 +737,20 @@ async function maybeEnqueueOnColumnEnter(task, previousColumn) {
     return { enqueued: false, reason: 'same_column' };
   }
 
-  const config = await loadConfig();
+  const config = await ensureBoardConfig();
   if (config.missing || !config.enabled) {
     return { enqueued: false, reason: config.missing ? 'no_config' : 'disabled' };
   }
 
+  if (!config.columns[task.column] || !config.columns[task.column].enabled) {
+    return { enqueued: false, reason: 'column_disabled' };
+  }
+
+  const agentField = agentForStage(config, task.column);
+  if (!agentField.enabled) {
+    return { enqueued: false, reason: 'agent_disabled' };
+  }
+
   // Dedup: already running this stage
   const wf = task.workflow;
   if (wf && wf.status === 'running' && wf.stage === task.column) {
@@ -449,12 +784,23 @@ async function waitForIdle(taskId, timeoutMs = 15000) {
   throw new Error(`waitForIdle timeout for task ${taskId}`);
 }
 
+async function planDoneColumn() {
+  const config = await ensureBoardConfig();
+  return config.plan_done_column;
+}
+
 module.exports = {
   loadConfig,
+  ensureBoardConfig,
+  clearConfigCache,
+  shapePublicConfig,
   maybeEnqueueOnColumnEnter,
   parseTestingVerdict,
   parseReviewGate,
   waitForIdle,
+  planDoneColumn,
+  buildTransitions,
+  DEFAULT_LABELS,
   JOBS_DIR,
   CONFIG_PATH
 };