kanbango 2.4.0 → 3.0.2

package/kanban.js

@@ -3,10 +3,6 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const COLS = ['active', 'planned', 'icebox', 'done'];
-const GUI_PORT_FILE = '.kanbango-gui.json';
-const GUI_PORT_MIN = 5510;
-const GUI_PORT_MAX = 5999;
-const GUI_PORT_SPAN = GUI_PORT_MAX - GUI_PORT_MIN + 1;
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
@@ -62,6 +58,16 @@ const VIEW_FIELDS = {
   ]
 };
 
+// Hard-required on create: title only (keeps GUI/CLI quick-add usable).
+// Strongly recommended for agent/planned work — missing ones yield warnings, not errors.
+const RECOMMENDED_CREATE_FIELDS = [
+  'description',
+  'specs',
+  'in_scope',
+  'out_of_scope',
+  'acceptance_criteria'
+];
+
 function createKanbanError(code, message, hint, details = {}, retryable = false, status = 400) {
   const error = new Error(message);
   error.code = code;
@@ -96,6 +102,36 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function isPresentCreateField(field, value) {
+  if (field === 'description' || field === 'specs' || field === 'notes') {
+    return Boolean(normalizeString(value));
+  }
+  if (
+    field === 'in_scope' ||
+    field === 'out_of_scope' ||
+    field === 'acceptance_criteria' ||
+    field === 'test_cases' ||
+    field === 'subtasks'
+  ) {
+    if (field === 'subtasks') return normalizeSubtasks(value).length > 0;
+    return normalizeStringArray(value).length > 0;
+  }
+  return value !== undefined && value !== null && value !== '';
+}
+
+function missingRecommendedCreateFields(payload = {}) {
+  return RECOMMENDED_CREATE_FIELDS.filter((field) => !isPresentCreateField(field, payload[field]));
+}
+
+function createFieldWarnings(payload = {}) {
+  const missing = missingRecommendedCreateFields(payload);
+  if (missing.length === 0) return [];
+  return [
+    `Strongly recommended fields missing: ${missing.join(', ')}. ` +
+      'Fill them on create (or via update) so scope and done-criteria are explicit.'
+  ];
+}
+
 function normalizeSubtasks(value) {
   if (!Array.isArray(value)) return [];
   return value.map((subtask, idx) => ({
@@ -343,7 +379,7 @@ async function findFile(epicId) {
       const candidates = files
         .filter((file) => (file.endsWith('.json') || file.endsWith('.md'))
           && path.basename(file, path.extname(file)) === epicId)
-        .sort((left, right) => (left.endsWith('.json') ? -1 : 1));
+        .sort((left, _right) => (left.endsWith('.json') ? -1 : 1));
       if (candidates[0]) {
         return path.join(colDir, candidates[0]);
       }
@@ -524,11 +560,6 @@ async function doCreate(title, column = 'planned', epicGroup = '—', extra = {}
   validateColumn(column, 'col');
 
   const nextId = await nextTaskNumber();
-  const slug = title
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .substring(0, 25);
   const task = normalizeTask({
     id: String(nextId).padStart(3, '0'),
     title,
@@ -729,118 +760,6 @@ async function doUpdate(epicId, newTitle, newTasks) {
   }
 }
 
-function guiPortFilePath() {
-  return path.join(BACKLOG, GUI_PORT_FILE);
-}
-
-function hashCwdToPort(cwd = process.cwd()) {
-  let hash = 0;
-  const input = String(cwd);
-  for (let i = 0; i < input.length; i++) {
-    hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
-  }
-  return GUI_PORT_MIN + (Math.abs(hash) % GUI_PORT_SPAN);
-}
-
-function normalizeGuiPort(value) {
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
-    return null;
-  }
-  return parsed;
-}
-
-function resolvePreferredGuiPort(explicitPort) {
-  if (explicitPort !== undefined && explicitPort !== null && explicitPort !== '') {
-    const fromArg = normalizeGuiPort(explicitPort);
-    if (fromArg) return fromArg;
-  }
-
-  const fromEnv = normalizeGuiPort(process.env.KANBANGO_GUI_PORT);
-  if (fromEnv) return fromEnv;
-
-  return hashCwdToPort(process.cwd());
-}
-
-function isPidAlive(pid) {
-  const n = Number.parseInt(pid, 10);
-  if (!Number.isFinite(n) || n <= 0) return false;
-  try {
-    process.kill(n, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function writeGuiPortFile({ port, pid = process.pid } = {}) {
-  const normalizedPort = normalizeGuiPort(port);
-  if (!normalizedPort) {
-    throw createKanbanError(
-      'VALIDATION_ERROR',
-      'Invalid GUI port',
-      'Use an integer between 1 and 65535',
-      { port },
-      false,
-      400
-    );
-  }
-
-  await ensureBacklogDir();
-  const data = {
-    port: normalizedPort,
-    pid,
-    url: `http://localhost:${normalizedPort}`,
-    cwd: process.cwd(),
-    started_at: new Date().toISOString()
-  };
-  await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
-  return data;
-}
-
-async function readGuiPortFile() {
-  try {
-    const raw = await fs.readFile(guiPortFilePath(), 'utf-8');
-    const data = JSON.parse(raw);
-    if (!data || !normalizeGuiPort(data.port)) return null;
-    return data;
-  } catch (error) {
-    if (error.code === 'ENOENT') return null;
-    return null;
-  }
-}
-
-async function clearGuiPortFile({ pid, force = false } = {}) {
-  const info = await readGuiPortFile();
-  if (!info) return false;
-  if (!force && pid !== undefined && info.pid !== pid) return false;
-  if (!force && pid === undefined && info.pid !== process.pid) return false;
-
-  try {
-    await fs.unlink(guiPortFilePath());
-    return true;
-  } catch (error) {
-    if (error.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-async function discoverRunningGui() {
-  const info = await readGuiPortFile();
-  if (!info || !isPidAlive(info.pid)) {
-    if (info) await clearGuiPortFile({ force: true });
-    return null;
-  }
-  return {
-    status: 'running',
-    port: info.port,
-    pid: info.pid,
-    url: info.url || `http://localhost:${info.port}`,
-    cwd: info.cwd,
-    started_at: info.started_at
-  };
-}
-
 module.exports = {
   ensureBacklogDir,
   parseEpic,
@@ -855,20 +774,12 @@ module.exports = {
   doUpdate,
   doCreate,
   createKanbanError,
+  createFieldWarnings,
+  missingRecommendedCreateFields,
   getProgress,
   resolveTaskId,
-  hashCwdToPort,
-  normalizeGuiPort,
-  resolvePreferredGuiPort,
-  isPidAlive,
-  writeGuiPortFile,
-  readGuiPortFile,
-  clearGuiPortFile,
-  discoverRunningGui,
-  guiPortFilePath,
   COLS,
   STATUS_MAP,
   VIEW_FIELDS,
-  GUI_PORT_MIN,
-  GUI_PORT_MAX
+  RECOMMENDED_CREATE_FIELDS
 };