@goodandready/dsh-goal 0.2.5 → 0.2.7

package/lib/engine-milestones.js

@@ -0,0 +1,106 @@
+import { MilestoneStatus } from './goal-engine-constants.js';
+
+/**
+ * Match a milestone object by exact ID or normalized ID (e.g. m-1 vs m1 vs 1)
+ * @param {object} m Milestone object
+ * @param {string|number} id Milestone ID to match
+ * @returns {boolean}
+ */
+export function matchMilestone(m, id) {
+  if (!m || id === undefined || id === null) return false;
+  if (m.id === String(id)) return true;
+  const s1 = String(m.id).toLowerCase().replace(/[^a-z0-9]/g, '');
+  const s2 = String(id).toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (s1 && s1 === s2) return true;
+  const n1 = s1.replace(/^m+/, '');
+  const n2 = s2.replace(/^m+/, '');
+  return Boolean(n1 && n1 === n2);
+}
+
+/**
+ * Safely parse checklist items
+ * @param {Array} checklist
+ * @returns {Array<{ text: string, done: boolean }>}
+ */
+export function parseChecklist(checklist) {
+  if (!Array.isArray(checklist)) return [];
+  return checklist
+    .map((item) => ({
+      text: String(item?.text || item?.title || '').trim(),
+      done: Boolean(item?.done || item?.completed),
+    }))
+    .filter((item) => item.text.length > 0);
+}
+
+/**
+ * Build and normalize milestone objects from list
+ * @param {Array} milestonesList
+ * @param {number} startingCount
+ * @returns {Array<object>}
+ */
+export function parseMilestoneItems(milestonesList, startingCount = 0) {
+  if (!Array.isArray(milestonesList)) return [];
+  const result = [];
+  let count = startingCount;
+
+  for (const item of milestonesList) {
+    const itemTitle = typeof item === 'string' ? item : item?.title;
+    if (!itemTitle || !itemTitle.trim()) continue;
+
+    count += 1;
+    const mId = typeof item === 'object' && item?.id ? item.id : ('m-' + count);
+    const mObj = {
+      id: String(mId),
+      title: itemTitle.trim(),
+      status: typeof item === 'object' && item?.status ? item.status : MilestoneStatus.PENDING,
+      notes: typeof item === 'object' && item?.notes ? String(item.notes) : '',
+    };
+    if (typeof item === 'object' && Array.isArray(item?.checklist)) {
+      mObj.checklist = parseChecklist(item.checklist);
+    }
+    result.push(mObj);
+  }
+
+  return result;
+}
+
+/**
+ * Apply updates to a milestone target
+ * @param {object} target Milestone object
+ * @param {string} [status] New status
+ * @param {string} [notes] New notes
+ * @param {Array} [checklist] New checklist
+ * @param {Array<string>} [validStatuses] Allowed statuses
+ * @returns {{ prevStatus: string, updatedStatus: string }}
+ */
+export function applyMilestoneUpdate(target, status, notes = '', checklist = null, validStatuses = []) {
+  if (!target) return { prevStatus: null, updatedStatus: null };
+  const prevStatus = target.status;
+
+  if (status && (validStatuses.length === 0 || validStatuses.includes(status))) {
+    target.status = status;
+  }
+  if (notes !== undefined && notes !== null && notes !== '') {
+    target.notes = String(notes);
+  }
+  if (Array.isArray(checklist)) {
+    target.checklist = parseChecklist(checklist);
+  }
+
+  return { prevStatus, updatedStatus: target.status };
+}
+
+/**
+ * Toggle a checklist item in milestone target
+ * @param {object} target Milestone object
+ * @param {number} itemIndex Index in checklist
+ * @param {boolean} [done] Optional explicit done boolean
+ * @returns {boolean}
+ */
+export function toggleMilestoneChecklistItem(target, itemIndex, done) {
+  if (!target || !Array.isArray(target.checklist) || !target.checklist[itemIndex]) {
+    return false;
+  }
+  target.checklist[itemIndex].done = done !== undefined ? Boolean(done) : !target.checklist[itemIndex].done;
+  return true;
+}

package/lib/engine-prompt.js

@@ -15,15 +15,37 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     }
   }
 
+  let budgetWarningText = '';
+  if (snapshot.budgetWarningTriggered) {
+    const total = snapshot.tokensUsage?.totalTokens || 0;
+    const max = snapshot.maxTokenBudget || 0;
+    const pct = max > 0 ? Math.round((total / max) * 100) : 0;
+    if (lang === 'zh') {
+      budgetWarningText = `\n\n⚠️ TOKEN 预算预警 (已消耗 ${pct}%: ${total.toLocaleString('en-US')}/${max.toLocaleString('en-US')}):\nToken 预算即将耗尽！严禁开展额外探索，必须专注于立即完成当前里程碑并调用 goal_finish 提交成果！\n`;
+    } else {
+      budgetWarningText = `\n\n⚠️ TOKEN BUDGET ALERT (${pct}% consumed: ${total.toLocaleString('en-US')}/${max.toLocaleString('en-US')}):\nToken budget is nearing exhaustion! Avoid exploratory turns and focus strictly on completing active milestones and calling goal_finish immediately!\n`;
+    }
+  }
+
+  const formatMilestone = (m, i) => {
+    let line = `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`;
+    if (Array.isArray(m.checklist) && m.checklist.length > 0) {
+      const checkLines = m.checklist
+        .map((item) => `      [${item.done ? 'x' : ' '}] ${item.text}`)
+        .join('\n');
+      line += `\n${checkLines}`;
+    }
+    return line;
+  };
+
   if (lang === 'zh') {
     const milestonesText = hasMilestones
-      ? snapshot.milestones
-          .map((m, i) => `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`)
-          .join('\n')
+      ? snapshot.milestones.map(formatMilestone).join('\n')
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
       nudgeText +
+      budgetWarningText +
       `\n\n[DSH GOAL MODE ACTIVE]\n` +
       `目标: "${snapshot.title}"\n` +
       `运行时间: ${snapshot.formattedElapsed}${etaText} | 迭代轮次: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
@@ -31,19 +53,18 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       `${milestonesText}\n\n` +
       `Goal Mode 执行契约 (必须严格遵循):\n` +
       `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
-      `2. 推进里程碑时，必须通过 goal_update_progress 工具更新状态（开始前标为 in_progress，完成后标为 completed 并附简要说明）。\n` +
+      `2. 推进里程碑时，必须通过 goal_update_progress 工具更新状态（开始前标为 in_progress，完成后标为 completed 并附简要说明）。如有细分子任务，可通过 checklist 字段同步进度。\n` +
       `3. 当所有里程碑全部完成后，调用 goal_finish 工具提交详细成果总结。`
     );
   }
 
   const milestonesText = hasMilestones
-    ? snapshot.milestones
-        .map((m, i) => `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${m.notes ? ` (${m.notes})` : ''}`)
-        .join('\n')
+    ? snapshot.milestones.map(formatMilestone).join('\n')
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
     nudgeText +
+    budgetWarningText +
     `\n\n[DSH GOAL MODE ACTIVE]\n` +
     `Goal: "${snapshot.title}"\n` +
     `Elapsed Time: ${snapshot.formattedElapsed}${etaText} | Iteration: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
@@ -51,7 +72,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     `${milestonesText}\n\n` +
     `Goal Mode Instructions (MANDATORY TO FOLLOW):\n` +
     `1. ${hasMilestones ? 'Execute the current active milestone from the work plan.' : 'YOUR FIRST STEP: Immediately call tool goal_set_milestones with the list of milestones (3-7 concrete steps). You must not execute work or finish turn without calling goal_set_milestones!'}\n` +
-    `2. As each milestone progresses, update its status via tool goal_update_progress (status: "in_progress" before starting, status: "completed" upon completion with brief notes).\n` +
+    `2. As each milestone progresses, update its status via tool goal_update_progress (status: "in_progress" before starting, status: "completed" upon completion with brief notes). If sub-tasks exist, pass checklist array to track items.\n` +
     `3. When all milestones are completed, call tool goal_finish with a detailed summary of achieved results.`
   );
 }

package/lib/engine-reports.js

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 
 /**
  * Safely get current short git commit hash
@@ -7,7 +7,7 @@ import { execSync } from 'node:child_process';
  */
 export function getGitCurrentCommit(cwd) {
   try {
-    return execSync('git rev-parse --short HEAD', {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
       timeout: 1000,
@@ -112,3 +112,109 @@ export function exportReportGitHubPR(state) {
   md += `*Automated by [@goodandready/dsh-goal](https://github.com/GooDAnDReaDY/dsh-goal)*\n`;
   return md;
 }
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Safely create a git milestone checkpoint
+ * @param {object} milestone
+ * @param {string} sessionId
+ * @param {string} [cwd]
+ * @returns {string|null} commit hash or tag name
+ */
+export function createMilestoneCheckpoint(milestone, sessionId = 'default', cwd) {
+  if (!milestone || !milestone.id) return null;
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+      cwd: cwd || undefined,
+    }).trim();
+
+    // If there are changes, auto-commit checkpoint
+    if (status) {
+      execFileSync('git', ['add', '-A'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 3000,
+        cwd: cwd || undefined,
+      });
+      const cleanTitle = (milestone.title || '').replace(/[\"\`\$]/g, '');
+      const msg = `checkpoint(goal): [${milestone.id}] ${cleanTitle}`;
+      execFileSync('git', ['commit', '-m', msg, '--no-verify'], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: 5000,
+        cwd: cwd || undefined,
+      });
+    }
+
+    const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+      cwd: cwd || undefined,
+    }).trim();
+
+    return hash || null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Rollback working tree to a specific commit checkpoint
+ * @param {string} commitHash
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+export function rollbackToCheckpoint(commitHash, cwd) {
+  if (!commitHash || typeof commitHash !== 'string') return false;
+  try {
+    const cleanHash = commitHash.trim().replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!cleanHash) return false;
+    execFileSync('git', ['checkout', cleanHash, '--', '.'], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout: 5000,
+      cwd: cwd || undefined,
+    });
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Save full goal execution artifact markdown file into .dsh/goals/
+ * @param {object} state
+ * @param {string} [cwd]
+ * @returns {{ relativePath: string, fullPath: string, content: string }|null}
+ */
+export function saveGoalArtifact(state, cwd) {
+  if (!state || !state.title) return null;
+  try {
+    const root = cwd || process.cwd();
+    const targetDir = path.join(root, '.dsh', 'goals');
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const safeTitle = (state.title || 'goal')
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 40) || 'run';
+
+    const filename = `${timestamp}-${safeTitle}.md`;
+    const fullPath = path.join(targetDir, filename);
+    const relativePath = path.join('.dsh', 'goals', filename).replace(/\\/g, '/');
+
+    const content = exportReportMarkdown(state);
+    fs.writeFileSync(fullPath, content, 'utf8');
+
+    return { relativePath, fullPath, content };
+  } catch (err) {
+    return null;
+  }
+}

package/lib/goal-engine-constants.js

@@ -98,3 +98,119 @@ export function sessionIdOf(invocationOrReq, fallback = 'default') {
   }
   return fallback;
 }
+
+/**
+ * Calculate elapsed seconds from goal timing properties
+ * @param {object} goal
+ * @returns {number}
+ */
+export function calculateElapsedSeconds(goal) {
+  if (!goal) return 0;
+  const { startedAt, pausedAt, totalPausedDurationMs, completedAt } = goal;
+  const endTime = completedAt || (pausedAt || Date.now());
+  const elapsedMs = Math.max(0, endTime - startedAt - (totalPausedDurationMs || 0));
+  return Math.floor(elapsedMs / 1000);
+}
+
+/**
+ * Calculate estimated remaining seconds based on completed milestones
+ * @param {object} goal
+ * @param {number} elapsed
+ * @returns {number|null}
+ */
+export function calculateRemainingSeconds(goal, elapsed) {
+  if (!goal || goal.state !== GoalState.RUNNING) return null;
+  const total = goal.milestones?.length || 0;
+  if (total === 0) return null;
+  const completedCount = goal.milestones.filter((m) => m.status === MilestoneStatus.COMPLETED).length;
+  if (completedCount === 0 || completedCount >= total) return null;
+  if (elapsed <= 0) return null;
+  const avgSecPerMilestone = elapsed / completedCount;
+  const remainingCount = total - completedCount;
+  return Math.max(1, Math.round(avgSecPerMilestone * remainingCount));
+}
+
+/**
+ * Build snapshot object for a given goal or idle state
+ * @param {object|null} goal
+ * @param {string} sid
+ * @param {object} engine
+ * @returns {object}
+ */
+export function buildSnapshot(goal, sid, engine) {
+  if (!goal) {
+    return {
+      sessionId: sid,
+      hasActiveGoal: false,
+      state: GoalState.IDLE,
+      title: '',
+      startedAt: null,
+      pausedAt: null,
+      totalPausedDurationMs: 0,
+      completedAt: null,
+      elapsedSeconds: 0,
+      formattedElapsed: '0s',
+      estimatedRemainingSeconds: null,
+      formattedETA: null,
+      lang: 'en',
+      tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      milestones: [],
+      progressPercent: 0,
+      iterationsCount: 0,
+      maxIterations: engine.defaultMaxIterations,
+      autoDrive: engine.autoDrive,
+      enableSound: engine.enableSound,
+      showQuickLaunchButton: engine.showQuickLaunchButton,
+      gitStartCommit: null,
+      pendingNudge: null,
+      toolFailureCount: 0,
+      consecutiveToolFailureLimit: engine.consecutiveToolFailureLimit,
+      maxTokenBudget: engine.maxTokenBudget,
+      budgetWarningThreshold: engine.budgetWarningThreshold,
+      budgetWarningTriggered: false,
+      autoCheckpointOnMilestone: engine.autoCheckpointOnMilestone,
+    };
+  }
+
+  const elapsed = calculateElapsedSeconds(goal);
+  const milestones = goal.milestones || [];
+  const completedCount = milestones.filter((m) => m.status === MilestoneStatus.COMPLETED).length;
+  const progressPercent = milestones.length > 0 ? Math.round((completedCount / milestones.length) * 100) : 0;
+  const estSec = calculateRemainingSeconds(goal, elapsed);
+
+  return {
+    sessionId: sid,
+    hasActiveGoal: true,
+    id: goal.id,
+    state: goal.state,
+    title: goal.title,
+    description: goal.description,
+    lang: goal.lang || detectLanguage(goal.title),
+    startedAt: goal.startedAt,
+    pausedAt: goal.pausedAt,
+    totalPausedDurationMs: goal.totalPausedDurationMs,
+    completedAt: goal.completedAt,
+    elapsedSeconds: elapsed,
+    formattedElapsed: formatElapsed(elapsed),
+    estimatedRemainingSeconds: estSec,
+    formattedETA: formatETA(estSec),
+    tokensUsage: goal.tokensUsage || { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    iterationsCount: goal.iterationsCount,
+    maxIterations: goal.maxIterations,
+    milestones,
+    progressPercent,
+    logs: goal.logs,
+    resultSummary: goal.resultSummary,
+    autoDrive: engine.autoDrive,
+    enableSound: engine.enableSound,
+    showQuickLaunchButton: engine.showQuickLaunchButton,
+    gitStartCommit: goal.gitStartCommit || null,
+    pendingNudge: goal.pendingNudge || null,
+    toolFailureCount: engine.getToolFailureCount(sid),
+    consecutiveToolFailureLimit: engine.consecutiveToolFailureLimit,
+    maxTokenBudget: goal.maxTokenBudget ?? engine.maxTokenBudget,
+    budgetWarningThreshold: engine.budgetWarningThreshold,
+    budgetWarningTriggered: Boolean(goal.budgetWarningTriggered),
+    autoCheckpointOnMilestone: engine.autoCheckpointOnMilestone,
+  };
+}