@goodandready/dsh-goal 0.2.29 → 0.2.31

package/lib/engine-diff.js

@@ -0,0 +1,147 @@
+import { execFileSync } from 'node:child_process';
+import { getSafeCwd } from './goal-engine-constants.js';
+import { isGitRepository, isValidGitRef } from './engine-git-branch.js';
+
+/**
+ * Parse git diff --numstat output into structured file statistics
+ * @param {string} output 
+ * @returns {Array<{ path: string, insertions: number, deletions: number, binary: boolean }>}
+ */
+export function parseNumstat(output) {
+  if (!output || typeof output !== 'string') return [];
+  const lines = output.trim().split('\n');
+  const files = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+    const [rawIns, rawDel, filePath] = parts;
+    const isBinary = rawIns === '-' || rawDel === '-';
+    const ins = isBinary ? 0 : parseInt(rawIns, 10) || 0;
+    const del = isBinary ? 0 : parseInt(rawDel, 10) || 0;
+    files.push({
+      path: filePath,
+      insertions: ins,
+      deletions: del,
+      binary: isBinary,
+    });
+  }
+  return files;
+}
+
+/**
+ * Get git diff between refs or current working tree
+ * @param {object} options
+ * @returns {object} diff result payload
+ */
+export function getGitDiff({
+  cwd = process.cwd(),
+  base,
+  target,
+  file,
+  allowedRoots = [],
+  maxBytes = 256 * 1024,
+} = {}) {
+  const safeCwd = getSafeCwd(cwd, allowedRoots);
+  if (!safeCwd || !isGitRepository(safeCwd, allowedRoots)) {
+    return { ok: false, error: 'Not a git repository or invalid path' };
+  }
+
+  // Ref validation: disallow flag injection and special chars
+  if (base && !isValidGitRef(base)) {
+    return { ok: false, error: 'Invalid base git ref' };
+  }
+  if (target && !isValidGitRef(target)) {
+    return { ok: false, error: 'Invalid target git ref' };
+  }
+  if (file && (typeof file !== 'string' || file.startsWith('-') || /[\0\r\n]/.test(file))) {
+    return { ok: false, error: 'Invalid file parameter' };
+  }
+
+  try {
+    const rangeArgs = [];
+    if (base && target) {
+      rangeArgs.push(`${base}..${target}`);
+    } else if (base) {
+      rangeArgs.push(base);
+    } else if (target) {
+      rangeArgs.push(target);
+    }
+
+    // 1. Fetch numstat for file summary
+    const numstatArgs = ['diff', '--numstat', ...rangeArgs];
+    if (file) {
+      numstatArgs.push('--', file);
+    }
+    const numstatOut = execFileSync('git', numstatArgs, {
+      cwd: safeCwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+
+    const files = parseNumstat(numstatOut);
+    const stats = {
+      filesChanged: files.length,
+      insertions: files.reduce((acc, f) => acc + f.insertions, 0),
+      deletions: files.reduce((acc, f) => acc + f.deletions, 0),
+    };
+
+    // 2. Fetch patch
+    const patchArgs = ['diff', '-p', '--no-color', ...rangeArgs];
+    if (file) {
+      patchArgs.push('--', file);
+    }
+    let patchOut = execFileSync('git', patchArgs, {
+      cwd: safeCwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+
+    let truncated = false;
+    if (patchOut.length > maxBytes) {
+      patchOut = patchOut.slice(0, maxBytes);
+      truncated = true;
+    }
+
+    return {
+      ok: true,
+      cwd: safeCwd,
+      base: base || null,
+      target: target || 'HEAD',
+      stats,
+      files,
+      diff: patchOut,
+      truncated,
+    };
+  } catch (err) {
+    return { ok: false, error: err.message || 'git diff execution failed' };
+  }
+}
+
+/**
+ * GoalEngine helper to fetch diff for active or specified session
+ * @param {object} engine 
+ * @param {string} sessionId 
+ * @param {object} options 
+ * @returns {object} diff result
+ */
+export function getEngineGoalDiff(engine, sessionId = 'default', options = {}) {
+  const sid = sessionId || 'default';
+  const goal = engine.goals?.get(sid);
+  const allowedRoots = options.allowedRoots || engine.config?.allowedRoots || (goal?.cwd ? [goal.cwd, process.cwd()] : [process.cwd()]);
+  const cwd = options.cwd || goal?.cwd || engine.config?.cwd || process.cwd();
+  const base = options.base || goal?.gitStartCommit || null;
+  const target = options.target || goal?.gitBranch || goal?.branchName || 'HEAD';
+
+  return getGitDiff({
+    cwd,
+    base,
+    target,
+    file: options.file,
+    allowedRoots,
+    maxBytes: options.maxBytes,
+  });
+}

package/lib/engine-kanban-sync.js

@@ -0,0 +1,242 @@
+import { MilestoneStatus } from './goal-engine-constants.js';
+
+export const MILESTONE_TO_KANBAN_COLUMN = {
+  [MilestoneStatus.PENDING]: 'todo',
+  [MilestoneStatus.IN_PROGRESS]: 'in_progress',
+  [MilestoneStatus.COMPLETED]: 'done',
+  pending: 'todo',
+  in_progress: 'in_progress',
+  active: 'in_progress',
+  completed: 'done',
+  PENDING: 'todo',
+  ACTIVE: 'in_progress',
+  COMPLETED: 'done',
+};
+
+export const KANBAN_COLUMN_TO_MILESTONE_STATUS = {
+  backlog: MilestoneStatus.PENDING,
+  todo: MilestoneStatus.PENDING,
+  in_progress: MilestoneStatus.IN_PROGRESS,
+  doing: MilestoneStatus.IN_PROGRESS,
+  active: MilestoneStatus.IN_PROGRESS,
+  review: MilestoneStatus.COMPLETED,
+  done: MilestoneStatus.COMPLETED,
+  completed: MilestoneStatus.COMPLETED,
+};
+
+/**
+ * Format externalRef string for a goal milestone
+ * @param {string} goalId 
+ * @param {string} milestoneId 
+ * @returns {string}
+ */
+export function formatMilestoneExternalRef(goalId, milestoneId) {
+  return `dsh-goal:${goalId || 'default'}:${milestoneId}`;
+}
+
+/**
+ * Parse milestone externalRef
+ * @param {string} externalRef 
+ * @returns {{ goalId: string, milestoneId: string } | null}
+ */
+export function parseMilestoneExternalRef(externalRef) {
+  if (typeof externalRef !== 'string' || !externalRef.startsWith('dsh-goal:')) {
+    return null;
+  }
+  const parts = externalRef.split(':');
+  if (parts.length < 3) return null;
+  return {
+    goalId: parts[1],
+    milestoneId: parts.slice(2).join(':'),
+  };
+}
+
+/**
+ * Resolve active kanban service or store from context/options
+ * @param {object} options 
+ * @returns {{ service: object | null, store: object | null }}
+ */
+export function resolveKanbanServices(options = {}) {
+  const ctx = options.ctx;
+  let service = options.kanbanService || null;
+  let store = options.store || null;
+
+  if (!service && ctx) {
+    service = ctx.dshKanban || (typeof ctx.get === 'function' ? ctx.get('dshKanban') : null);
+  }
+
+  if (!store) {
+    if (service && typeof service.getStore === 'function') {
+      store = service.getStore();
+    } else if (ctx?.kanbanStore) {
+      store = ctx.kanbanStore;
+    }
+  }
+
+  return { service, store };
+}
+
+/**
+ * Synchronize all milestones of a goal with dsh-kanban
+ * Safe degradation if kanban is not available
+ * @param {object} engine 
+ * @param {string} sessionId 
+ * @param {object} options 
+ * @returns {Promise<object>} sync summary
+ */
+export async function syncGoalToKanban(engine, sessionId = 'default', options = {}) {
+  const sid = sessionId || 'default';
+  const goal = engine.goals?.get(sid);
+  if (!goal) {
+    return { ok: false, error: 'Goal not found' };
+  }
+  if (!goal.milestones || goal.milestones.length === 0) {
+    return { ok: true, synced: 0, reason: 'No milestones in goal' };
+  }
+
+  const { service, store } = resolveKanbanServices({
+    kanbanService: options.kanbanService || engine.kanbanService,
+    store: options.store || engine.kanbanStore,
+    ctx: options.ctx || engine.ctx,
+    ...options,
+  });
+
+  if (!service && !store) {
+    return { ok: false, skipped: true, reason: 'kanban-unavailable' };
+  }
+
+  const results = [];
+  for (const ms of goal.milestones) {
+    const externalRef = formatMilestoneExternalRef(goal.id, ms.id);
+    const col = MILESTONE_TO_KANBAN_COLUMN[ms.status] || 'todo';
+    const title = `[Goal] ${ms.title}`;
+    const body = ms.notes || `Milestone ${ms.id} for goal: ${goal.title}`;
+
+    try {
+      if (service && typeof service.createTask === 'function') {
+        const res = await service.createTask({
+          title,
+          body,
+          column: col,
+          externalRef,
+          labels: ['dsh-goal', String(goal.id)],
+        });
+        results.push({ milestoneId: ms.id, taskId: res.taskId || res.task?.id, ok: res.ok, alreadyExists: res.alreadyExists });
+      } else if (store && typeof store.createTask === 'function') {
+        const existing = typeof store.findTaskByExternalRef === 'function' ? store.findTaskByExternalRef(externalRef) : null;
+        if (!existing) {
+          const task = store.createTask({
+            title,
+            body,
+            column: col,
+            externalRef,
+            labels: ['dsh-goal', String(goal.id)],
+          });
+          results.push({ milestoneId: ms.id, taskId: task.id, ok: true, alreadyExists: false });
+        } else {
+          results.push({ milestoneId: ms.id, taskId: existing.id, ok: true, alreadyExists: true });
+        }
+      }
+    } catch (err) {
+      engine.logger?.warn?.(`[dsh-goal] Kanban milestone sync failed for ${ms.id}:`, err?.message || err);
+      results.push({ milestoneId: ms.id, ok: false, error: err?.message || String(err) });
+    }
+  }
+
+  return { ok: true, synced: results.filter((r) => r.ok).length, total: goal.milestones.length, results };
+}
+
+/**
+ * Update corresponding kanban card column when milestone status changes
+ * @param {object} milestone 
+ * @param {object} options 
+ * @returns {Promise<object>}
+ */
+export async function syncMilestoneStatusToKanban(milestone, { goal, ctx, store, kanbanService } = {}) {
+  if (!milestone || !goal) return { ok: false, error: 'Invalid milestone or goal' };
+
+  const { store: activeStore } = resolveKanbanServices({
+    store,
+    kanbanService,
+    ctx,
+  });
+  if (!activeStore || typeof activeStore.findTaskByExternalRef !== 'function') {
+    return { ok: false, skipped: true, reason: 'kanban-store-unavailable' };
+  }
+
+  const externalRef = formatMilestoneExternalRef(goal.id, milestone.id);
+  const targetCol = MILESTONE_TO_KANBAN_COLUMN[milestone.status] || 'todo';
+
+  try {
+    const task = activeStore.findTaskByExternalRef(externalRef);
+    if (!task) {
+      return { ok: false, skipped: true, reason: 'kanban-task-not-found' };
+    }
+
+    if (task.column !== targetCol && typeof activeStore.moveTask === 'function') {
+      activeStore.moveTask(task.id, { column: targetCol });
+      return { ok: true, synced: true, taskId: task.id, column: targetCol };
+    }
+
+    return { ok: true, synced: true, taskId: task.id, column: task.column, unchanged: true };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+/**
+ * Handle external card movement from dsh-kanban board
+ * @param {object} engine 
+ * @param {object} payload 
+ * @param {string} sessionId 
+ * @returns {object}
+ */
+export function handleKanbanCardMoved(engine, payload = {}, sessionId = 'default') {
+  const externalRef = payload.externalRef;
+  const column = payload.column;
+  const targetStatus = payload.status || (column ? KANBAN_COLUMN_TO_MILESTONE_STATUS[column] : null);
+
+  if (!targetStatus) {
+    return { ok: false, error: 'Invalid or missing target milestone status/column' };
+  }
+
+  let goalId = null;
+  let milestoneId = payload.milestoneId || null;
+
+  if (externalRef) {
+    const parsed = parseMilestoneExternalRef(externalRef);
+    if (parsed) {
+      goalId = parsed.goalId;
+      milestoneId = parsed.milestoneId;
+    }
+  }
+
+  const candidateSessions = sessionId && sessionId !== 'default'
+    ? [sessionId, 'default']
+    : ['default', ...engine.goals.keys()];
+
+  for (const sid of candidateSessions) {
+    const goal = engine.goals?.get(sid);
+    if (!goal || (goalId && String(goal.id) !== String(goalId))) continue;
+
+    const ms = goal.milestones?.find((m) => String(m.id) === String(milestoneId) || m.title === payload.title);
+    if (ms) {
+      const updateRes = engine.updateMilestone(
+        ms.id,
+        targetStatus,
+        `Synced from Kanban card move to column '${column || targetStatus}'`,
+        sid
+      );
+      return {
+        ok: true,
+        sessionId: sid,
+        milestoneId: ms.id,
+        prevStatus: ms.status,
+        newStatus: targetStatus,
+        updateResult: updateRes,
+      };
+    }
+  }
+
+  return { ok: false, error: 'Matching milestone not found for external reference' };
+}

package/lib/engine-operator-query.js

@@ -0,0 +1,161 @@
+import { GoalState } from './goal-engine-constants.js';
+import { recordActivity } from './engine-intervention.js';
+
+/**
+ * Ask the human operator a question when encountering ambiguity or critical decisions (#166).
+ * Sets the goal into a waiting/paused state and records the query.
+ *
+ * @param {object} goal
+ * @param {object} query
+ * @param {string} query.question - Question text
+ * @param {string[]} [query.options] - Predefined choices for the operator
+ * @param {boolean} [query.isBlocking=true] - Whether to pause execution until answered
+ * @returns {object} result
+ */
+export function askOperatorQuery(goal, query = {}) {
+  if (!goal) {
+    return { ok: false, error: 'No active goal' };
+  }
+
+  const rawQ = query.question ? String(query.question).trim() : '';
+  if (!rawQ) {
+    return { ok: false, error: 'Question text is required' };
+  }
+
+  const cleanOptions = Array.isArray(query.options)
+    ? query.options.map((o) => String(o).trim()).filter(Boolean)
+    : [];
+
+  const isBlocking = query.isBlocking !== false;
+
+  const queryId = `opq-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  goal.operatorQuery = {
+    id: queryId,
+    question: rawQ,
+    options: cleanOptions,
+    isBlocking,
+    askedAt: Date.now(),
+    answeredAt: null,
+    answer: null,
+    optionIndex: null,
+    consumed: false,
+  };
+
+  goal.waitingForOperator = true;
+
+  if (isBlocking) {
+    if (!goal.previousStateBeforeOperator) {
+      goal.previousStateBeforeOperator = goal.state || GoalState.RUNNING;
+    }
+    goal.state = GoalState.PAUSED;
+    if (!goal.pausedAt) {
+      goal.pausedAt = Date.now();
+    }
+  }
+
+  recordActivity(goal, {
+    type: 'operator_query',
+    tool: 'goal_ask_operator',
+    status: 'pending',
+    details: `Asked operator: "${rawQ.slice(0, 80)}"`,
+  });
+
+  if (!Array.isArray(goal.logs)) goal.logs = [];
+  goal.logs.push({
+    timestamp: Date.now(),
+    type: 'warning',
+    message: `Goal awaiting operator input: "${rawQ}"`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+
+  return { ok: true, queryId, question: rawQ, options: cleanOptions, isBlocking };
+}
+
+/**
+ * Record operator response to a pending query and resume goal execution (#166).
+ *
+ * @param {object} goal
+ * @param {object} payload
+ * @param {string} [payload.answer] - Freeform text answer
+ * @param {number} [payload.optionIndex] - Index of selected choice in options array
+ * @returns {object} result
+ */
+export function answerOperatorQuery(goal, payload = {}) {
+  if (!goal || !goal.operatorQuery || !goal.waitingForOperator) {
+    return { ok: false, error: 'No pending operator query for this goal' };
+  }
+
+  let finalAnswer = typeof payload.answer === 'string' ? payload.answer.trim() : '';
+  const optIdx = typeof payload.optionIndex === 'number' ? payload.optionIndex : null;
+
+  if (optIdx !== null && Array.isArray(goal.operatorQuery.options) && goal.operatorQuery.options[optIdx]) {
+    finalAnswer = goal.operatorQuery.options[optIdx];
+  }
+
+  if (!finalAnswer) {
+    return { ok: false, error: 'Answer or valid option selection is required' };
+  }
+
+  goal.operatorQuery.answeredAt = Date.now();
+  goal.operatorQuery.answer = finalAnswer;
+  goal.operatorQuery.optionIndex = optIdx;
+  goal.operatorQuery.consumed = false;
+  goal.waitingForOperator = false;
+
+  // Unpause if goal was paused for operator
+  if (goal.pausedAt) {
+    const pauseMs = Math.max(0, Date.now() - goal.pausedAt);
+    goal.totalPausedDurationMs = (goal.totalPausedDurationMs || 0) + pauseMs;
+    goal.pausedAt = null;
+  }
+
+  goal.state = goal.previousStateBeforeOperator || GoalState.RUNNING;
+  delete goal.previousStateBeforeOperator;
+
+  recordActivity(goal, {
+    type: 'operator_answer',
+    tool: 'goal_ask_operator',
+    status: 'success',
+    details: `Operator replied: "${finalAnswer.slice(0, 80)}"`,
+  });
+
+  if (!Array.isArray(goal.logs)) goal.logs = [];
+  goal.logs.push({
+    timestamp: Date.now(),
+    type: 'info',
+    message: `Operator answered: "${finalAnswer}"`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+
+  return { ok: true, answer: finalAnswer };
+}
+
+/**
+ * Format prompt injection with operator's answer for the next turn.
+ * Marks the answer as consumed after formatting.
+ *
+ * @param {object} goal
+ * @param {string} [lang='en']
+ * @returns {string} formatted prompt snippet or empty string
+ */
+export function formatOperatorAnswerPrompt(goal, lang = 'en') {
+  if (!goal || !goal.operatorQuery || !goal.operatorQuery.answer || goal.operatorQuery.consumed) {
+    return '';
+  }
+
+  const { question, answer } = goal.operatorQuery;
+  // Mark consumed so it is only injected on the resume turn
+  goal.operatorQuery.consumed = true;
+
+  if (lang === 'zh') {
+    return `\n\n[操作员答复 / OPERATOR RESPONSE]\n` +
+      `你之前提出的问题: "${question}"\n` +
+      `操作员给出的明确指令: "${answer}"\n` +
+      `请严格根据操作员的答复继续推进任务，切勿再对此问题做无谓猜测！\n`;
+  }
+
+  return `\n\n[OPERATOR RESPONSE TO YOUR QUERY]\n` +
+    `Your Question: "${question}"\n` +
+    `Operator Answer: "${answer}"\n` +
+    `Strictly follow the operator's response and proceed with executing the goal without second-guessing!\n`;
+}

package/lib/engine-prompt.js

@@ -9,6 +9,16 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
   const hasMilestones = snapshot.milestones && snapshot.milestones.length > 0;
   const etaText = snapshot.formattedETA ? ` (ETA: ${snapshot.formattedETA})` : '';
 
+  let operatorAnswerText = '';
+  if (snapshot.operatorQuery?.answer && !snapshot.operatorQuery.consumed) {
+    snapshot.operatorQuery.consumed = true;
+    if (lang === 'zh') {
+      operatorAnswerText = `\n\n[操作员答复 / OPERATOR RESPONSE]\n你之前提出的问题: "${snapshot.operatorQuery.question}"\n操作员给出的明确指令: "${snapshot.operatorQuery.answer}"\n请严格根据操作员的答复继续推进任务，切勿再对此问题做无谓猜测！\n`;
+    } else {
+      operatorAnswerText = `\n\n[OPERATOR RESPONSE TO YOUR QUERY]\nYour Question: "${snapshot.operatorQuery.question}"\nOperator Answer: "${snapshot.operatorQuery.answer}"\nStrictly follow the operator's response and proceed with executing the goal without second-guessing!\n`;
+    }
+  }
+
   let directiveText = '';
   if (snapshot.userDirective && !snapshot.userDirectiveConsumed) {
     if (lang === 'zh') {
@@ -67,6 +77,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
+      operatorAnswerText +
       directiveText +
       nudgeText +
       budgetWarningText +
@@ -87,6 +98,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
+    operatorAnswerText +
     directiveText +
     nudgeText +
     budgetWarningText +

package/lib/engine-templates.js

@@ -1,3 +1,16 @@
+/**
+ * Format template string by replacing {{key}} with provided variable value (#165)
+ * @param {string} templateStr
+ * @param {object} vars
+ * @returns {string}
+ */
+export function formatTemplateVariables(templateStr, vars = {}) {
+  if (!templateStr || typeof templateStr !== "string") return "";
+  return templateStr.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, (_, key) => {
+    return vars && vars[key] != null && vars[key] !== "" ? String(vars[key]) : "";
+  }).trim();
+}
+
 import { MilestoneStatus } from './goal-engine-constants.js';
 
 /**
@@ -93,8 +106,8 @@ export function instantiateTemplate(templateId, inputValues = {}) {
   const tpl = GOAL_TEMPLATES.find((t) => t.id === templateId);
   if (!tpl) return null;
 
-  let title = tpl.title;
-  let description = tpl.description;
+  let title = tpl.promptTemplate ? formatTemplateVariables(tpl.promptTemplate, inputValues) : tpl.title;
+  let description = tpl.descriptionTemplate ? formatTemplateVariables(tpl.descriptionTemplate, inputValues) : tpl.description;
   if (inputValues.targetFile) {
     title = `Refactor ${inputValues.targetFile}`;
     description = `Decompose ${inputValues.targetFile} to < ${inputValues.lineThreshold || 500} lines`;

package/lib/goal-engine-constants.js

@@ -192,6 +192,8 @@ export function buildSnapshot(goal, sid, engine) {
       enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
       soundScheme: engine.soundScheme ?? 'default',
       enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+      operatorQuery: null,
+      waitingForOperator: false,
     };
   }
 
@@ -251,6 +253,8 @@ export function buildSnapshot(goal, sid, engine) {
     enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
     soundScheme: engine.soundScheme ?? 'default',
     enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+    operatorQuery: goal.operatorQuery || null,
+    waitingForOperator: Boolean(goal.waitingForOperator),
   };
 }