@goodandready/dsh-kanban 0.2.36 → 0.2.38

package/lib/config.js

@@ -96,6 +96,8 @@ export const CONFIG_DEFAULTS = {
   watchdogMaxConsecutiveErrors: 5,
   timeMachineEnabled: true,
   timeMachineAutoSnapshot: true,
+  notificationsEnabled: false,
+  audioAlertsEnabled: false,
 }
 
 /** Field descriptions reused in schema and settings card. */
@@ -151,6 +153,8 @@ export const CONFIG_HINTS = {
   watchdogMaxConsecutiveErrors: 'Number of consecutive execution errors before tripping circuit breaker (default: 5).',
   timeMachineEnabled: 'Enable integration with @goodandready/dsh-time-machine for task checkpoints and rollback.',
   timeMachineAutoSnapshot: 'Automatically create inception snapshot when task transitions to in-progress.',
+  notificationsEnabled: 'Enable desktop push notifications for key task events.',
+  audioAlertsEnabled: 'Enable Web Audio synthesized audio alerts on task transitions.',
 }
 
 /** Setting key for column WIP limit; not all columns have limits. */

package/lib/launcher.js

@@ -11,6 +11,7 @@
 // are passed as parameters to support unit testing without harness runtime.
 
 import { isAbsolute, join, resolve, sep } from 'node:path'
+import { formatPlanPrompt } from './plan-generator.js'
 import { randomUUID } from 'node:crypto'
 import { createTaskWorktree, registerDshWorkspace, isGitRepo } from './worktree.js'
 import { formatHandoverPreamble, parseProgressDump } from './progress-dump.js'
@@ -90,10 +91,13 @@ export function buildStartMessage(task, config) {
     ? `Task ${vars.repo}#${vars.issueNumber}: ${vars.title}`
     : `Task: ${vars.title}`
 
+  const planBlock = formatPlanPrompt(task)
+
   return joinBlocks([
     head,
     vars.body,
     fromIssue && vars.issueUrl !== '' ? `Link: ${vars.issueUrl}` : '',
+    planBlock,
     fromIssue ? WORKFLOW_TAIL : OWN_TAIL,
     note,
   ])

package/lib/plan-generator.js

@@ -0,0 +1,226 @@
+// Technical specification and execution plan generator for backlog/todo tasks (#376).
+// Zero Cyrillic literals in lib/ per Issue #366.
+
+import { MAX_ITEMS } from './plan.js'
+
+/**
+ * Truncate clean item text to reasonable single-line display length.
+ *
+ * @param {string} text Raw item text
+ * @returns {string} Truncated clean item
+ */
+function cleanItemText(text) {
+  const cleaned = String(text ?? '').replace(/\s+/g, ' ').trim()
+  return cleaned.length > 120 ? cleaned.slice(0, 119) + '…' : cleaned
+}
+
+/**
+ * Infer primary scope category from title, labels or body.
+ *
+ * @param {object} task Task record
+ * @returns {string} Scope name
+ */
+export function inferScope(task) {
+  const title = String(task?.title ?? '').toLowerCase()
+  const labels = Array.isArray(task?.labels) ? task.labels.map((l) => String(l).toLowerCase()) : []
+  for (const label of labels) {
+    if (label.startsWith('scope/')) return label.slice(6)
+  }
+  if (title.includes('ui') || title.includes('view') || title.includes('board') || title.includes('card')) return 'webui'
+  if (title.includes('tool') || title.includes('agent')) return 'agent-tools'
+  if (title.includes('setting') || title.includes('config')) return 'settings'
+  if (title.includes('worktree') || title.includes('branch') || title.includes('git')) return 'worktree'
+  if (title.includes('security') || title.includes('auth')) return 'security'
+  if (title.includes('route') || title.includes('api') || title.includes('server')) return 'routing'
+  return 'core'
+}
+
+/**
+ * Infer candidate files touched from task description and scope.
+ *
+ * @param {object} task Task record
+ * @param {string} scope Inferred or explicit scope
+ * @returns {string[]} List of candidate file paths
+ */
+export function inferCandidateFiles(task, scope) {
+  const body = String(task?.body ?? '')
+  const title = String(task?.title ?? '')
+  const combined = `${title}\n${body}`
+
+  const found = new Set()
+  // Match explicit file paths mentioned in markdown
+  const pathMatches = combined.match(/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_./-]+\.(js|mjs|json|md|yml|yaml|css|html)/g)
+  if (pathMatches) {
+    for (const p of pathMatches) {
+      if (!p.startsWith('node_modules/') && !p.startsWith('.git/')) {
+        found.add(p)
+      }
+    }
+  }
+
+  // Add scope-based canonical files if set is small
+  if (found.size === 0) {
+    if (scope === 'webui') {
+      found.add('lib/client.js')
+      found.add('test/board-ui.test.mjs')
+    } else if (scope === 'settings') {
+      found.add('lib/config.js')
+      found.add('lib/client.js')
+      found.add('test/config.test.mjs')
+    } else if (scope === 'agent-tools') {
+      found.add('lib/board-tool.js')
+      found.add('test/board-tool.test.mjs')
+    } else if (scope === 'worktree') {
+      found.add('lib/worktree.js')
+      found.add('test/worktree.test.mjs')
+    } else if (scope === 'routing') {
+      found.add('lib/routes.js')
+      found.add('lib/server/route-handlers.js')
+      found.add('test/routes.test.mjs')
+    } else {
+      found.add('lib/store.js')
+      found.add('test/store.test.mjs')
+    }
+    found.add('CHANGELOG.md')
+    found.add('docs/design/DESIGN.md')
+  }
+
+  return Array.from(found).slice(0, 10)
+}
+
+/**
+ * Generate technical specification and structured plan for a backlog task (#376).
+ *
+ * @param {object} task Task object
+ * @param {object} [options]
+ * @param {string} [options.customInstructions]
+ * @param {string[]} [options.additionalFiles]
+ * @returns {{ spec: string, items: string[], summary: string, scope: string }}
+ */
+export function generateTechnicalSpec(task, options = {}) {
+  const title = String(task?.title ?? '').trim()
+  const body = String(task?.body ?? '').trim()
+  const issueNum = typeof task?.issueNumber === 'number' ? task.issueNumber : null
+  const issueTag = issueNum ? ` #${issueNum}` : ''
+  const scope = inferScope(task)
+
+  const candidateFiles = inferCandidateFiles(task, scope)
+  if (Array.isArray(options.additionalFiles)) {
+    for (const f of options.additionalFiles) {
+      if (typeof f === 'string' && f.trim() !== '') candidateFiles.push(f.trim())
+    }
+  }
+
+  const items = [
+    `1. Preflight: inspect requirements and existing files for ${title}`,
+    `2. Domain logic: implement core algorithms and validation rules`,
+    `3. Data layer: update schema, storage methods and routes if needed`,
+    `4. Integration & UI: connect route handlers, client views, and translations`,
+    `5. Verification: run automated test suite and ensure zero regressions`,
+  ]
+
+  const specLines = [
+    `# Technical Specification: ${title}${issueTag}`,
+    '',
+    '## 1. Problem Statement & Context',
+    body ? body : 'No detailed description provided. Analyze issue requirements from title.',
+    '',
+    '## 2. Target Components & Candidate Files',
+    ...candidateFiles.map((f) => `- \`${f}\``),
+    '',
+    '## 3. Step-by-Step Implementation Algorithm',
+    ...items.map((it) => it),
+    '',
+    '## 4. Edge Cases & Validation Rules',
+    '- Validate non-empty inputs and fail-closed error boundaries.',
+    '- Ensure backward compatibility with existing schemas and configs.',
+    '- Keep all handwritten files under 600 lines with zero Cyrillic literals in lib/.',
+    '- Maintain client bundle size strictly under 256,000 bytes limit.',
+    '',
+    '## 5. Verification Plan',
+    '- Unit test coverage covering happy paths and edge cases.',
+    '- Full test suite execution: npm test.',
+    '- Runtime smoke check on live server instance.',
+  ]
+
+  if (typeof options.customInstructions === 'string' && options.customInstructions.trim() !== '') {
+    specLines.push('', '## 6. Special Instructions', options.customInstructions.trim())
+  }
+
+  const spec = specLines.join('\n')
+  const summary = `Spec generated for ${title}${issueTag}: ${candidateFiles.length} files targeted, ${items.length} plan steps.`
+
+  return {
+    spec,
+    items: items.map(cleanItemText).slice(0, MAX_ITEMS),
+    summary,
+    scope,
+  }
+}
+
+/**
+ * Extract step-by-step items from markdown text.
+ *
+ * @param {string} markdown Raw markdown text
+ * @returns {string[]} List of extracted plan items
+ */
+export function extractPlanItems(markdown) {
+  if (typeof markdown !== 'string' || !markdown.trim()) return []
+  const lines = markdown.split('\n')
+  const items = []
+  let inAlgorithmSection = false
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('#')) {
+      const lower = trimmed.toLowerCase()
+      inAlgorithmSection = lower.includes('algorithm') || lower.includes('step') || lower.includes('plan')
+      continue
+    }
+
+    if (inAlgorithmSection || !items.length) {
+      const hasPrefix = /^(?:\d+\.|\-|\*|\[[\sxX]\])/.test(trimmed)
+      const match = trimmed.match(/^(?:(?:\d+\.|\-|\*)\s+)?(?:\[[\sxX]\]\s+)?(.+)$/)
+      if (hasPrefix && match && match[1]) {
+        const item = cleanItemText(match[1])
+        if (item) items.push(item)
+      }
+    }
+  }
+
+  return items.slice(0, MAX_ITEMS)
+}
+
+/**
+ * Parse markdown specification into structured representation.
+ *
+ * @param {string} markdown Raw markdown spec
+ * @returns {{ spec: string, items: string[] }}
+ */
+export function parseSpecMarkdown(markdown) {
+  const spec = typeof markdown === 'string' ? markdown.trim() : ''
+  const items = extractPlanItems(spec)
+  return { spec, items }
+}
+
+/**
+ * Format technical specification and plan into prompt string for agent.
+ *
+ * @param {object} task Task object
+ * @returns {string} Formatted markdown prompt section or empty string
+ */
+export function formatPlanPrompt(task) {
+  if (!task) return ''
+  const spec = typeof task.spec === 'string' ? task.spec.trim() : ''
+  const items = Array.isArray(task.plan?.items) ? task.plan.items : []
+
+  if (spec) {
+    return `### Approved Technical Specification & Implementation Plan:\n\n${spec}`
+  }
+
+  if (items.length > 0) {
+    return `### Approved Implementation Plan Steps:\n\n${items.map((it, idx) => `${idx + 1}. ${it}`).join('\n')}`
+  }
+
+  return ''
+}

package/lib/pr-generator.js

@@ -0,0 +1,270 @@
+// Pull Request description and release notes generator (#379).
+// Zero Cyrillic literals in lib/ per Issue #366.
+
+import { inferScope } from './plan-generator.js'
+
+/**
+ * Parse one-line git log output into structured commit records.
+ *
+ * @param {string} logText Raw git log output
+ * @returns {Array<{ sha: string, message: string }>}
+ */
+export function parseGitLog(logText) {
+  if (typeof logText !== 'string' || !logText.trim()) return []
+  const lines = logText.trim().split('\n')
+  const commits = []
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+
+    // Tab-delimited (git log --pretty=format:%h%x09%s) or space-delimited
+    let sha = ''
+    let message = ''
+    if (trimmed.includes('\t')) {
+      const parts = trimmed.split('\t')
+      sha = parts[0].trim()
+      message = parts.slice(1).join('\t').trim()
+    } else {
+      const match = trimmed.match(/^([a-f0-9]{7,40})\s+(.+)$/i)
+      if (match) {
+        sha = match[1]
+        message = match[2].trim()
+      } else {
+        message = trimmed
+      }
+    }
+
+    if (sha || message) {
+      commits.push({ sha, message })
+    }
+  }
+
+  return commits
+}
+
+/**
+ * Parse git diff --stat output into structured file and line counts.
+ *
+ * @param {string} statText Raw git diff --stat output
+ * @returns {{ filesChanged: number, additions: number, deletions: number, files: Array<{ path: string, changes: string }> }}
+ */
+export function parseDiffStat(statText) {
+  if (typeof statText !== 'string' || !statText.trim()) {
+    return { filesChanged: 0, additions: 0, deletions: 0, files: [] }
+  }
+
+  const lines = statText.trim().split('\n')
+  const files = []
+  let filesChanged = 0
+  let additions = 0
+  let deletions = 0
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+
+    // Summary line: "3 files changed, 45 insertions(+), 12 deletions(-)"
+    const summaryMatch = trimmed.match(/(\d+)\s+files?\s+changed(?:,\s+(\d+)\s+insertions?\(\+\))?(?:,\s+(\d+)\s+deletions?\(-\))?/)
+    if (summaryMatch) {
+      filesChanged = parseInt(summaryMatch[1], 10) || 0
+      additions = parseInt(summaryMatch[2], 10) || 0
+      deletions = parseInt(summaryMatch[3], 10) || 0
+      continue
+    }
+
+    // File line: "lib/client.js | 14 +++++++-------"
+    const fileMatch = trimmed.match(/^(.+?)\s+\|\s+(\d+)\s*(.*)$/)
+    if (fileMatch) {
+      files.push({
+        path: fileMatch[1].trim(),
+        changes: fileMatch[2].trim(),
+      })
+    }
+  }
+
+  if (filesChanged === 0 && files.length > 0) {
+    filesChanged = files.length
+  }
+
+  return { filesChanged, additions, deletions, files }
+}
+
+/**
+ * Infer conventional commit / PR type (feat, fix, refactor, perf, docs, chore).
+ *
+ * @param {object} task Task object
+ * @param {Array<{ sha: string, message: string }>} [commits]
+ * @returns {string} PR type
+ */
+export function inferPrType(task, commits = []) {
+  const title = String(task?.title ?? '').toLowerCase()
+  const labels = Array.isArray(task?.labels) ? task.labels.map((l) => String(l).toLowerCase()) : []
+
+  for (const label of labels) {
+    if (label.startsWith('type/')) {
+      const t = label.slice(5)
+      if (t === 'bug') return 'fix'
+      if (t === 'feature') return 'feat'
+      return t
+    }
+  }
+
+  if (title.startsWith('fix:') || title.includes('fix') || title.includes('bug')) return 'fix'
+  if (title.startsWith('refactor:') || title.includes('refactor')) return 'refactor'
+  if (title.startsWith('perf:') || title.includes('performance')) return 'perf'
+  if (title.startsWith('docs:') || title.includes('document')) return 'docs'
+  if (title.startsWith('chore:') || title.includes('cleanup')) return 'chore'
+
+  for (const c of commits) {
+    const msg = String(c?.message ?? '').toLowerCase()
+    if (msg.startsWith('fix')) return 'fix'
+    if (msg.startsWith('refactor')) return 'refactor'
+    if (msg.startsWith('perf')) return 'perf'
+  }
+
+  return 'feat'
+}
+
+/**
+ * Generate canonical PR title according to conventional commits format.
+ *
+ * @param {object} task Task object
+ * @param {Array<{ sha: string, message: string }>} [commits]
+ * @returns {string} PR title
+ */
+export function generatePrTitle(task, commits = []) {
+  const type = inferPrType(task, commits)
+  const scope = inferScope(task)
+  let cleanTitle = String(task?.title ?? '').trim()
+
+  // Strip leading prefixes like "L: Feature:", "M: Fix:", "feat:", etc.
+  cleanTitle = cleanTitle.replace(/^[A-Z]:\s*(Feature|Bug|Fix|Refactor|Task):\s*/i, '')
+  cleanTitle = cleanTitle.replace(/^(feat|fix|refactor|perf|docs|chore)(\([^)]+\))?:\s*/i, '')
+
+  const issueNum = typeof task?.issueNumber === 'number' ? task.issueNumber : null
+  const issueRef = issueNum ? ` (#${issueNum})` : ''
+
+  return `${type}(${scope}): ${cleanTitle}${issueRef}`
+}
+
+/**
+ * Generate canonical, structured Pull Request description markdown (#379).
+ *
+ * @param {object} params
+ * @param {object} params.task Task record
+ * @param {Array<{ sha: string, message: string }>} [params.commits]
+ * @param {object} [params.diffStats]
+ * @param {object} [params.verification]
+ * @returns {string} Complete Markdown description for PR
+ */
+export function generatePrDescription({ task, commits = [], diffStats = null, verification = null }) {
+  const title = String(task?.title ?? '').trim()
+  const body = String(task?.body ?? '').trim()
+  const issueNum = typeof task?.issueNumber === 'number' ? task.issueNumber : null
+  const issueRef = issueNum ? `Closes #${issueNum}` : ''
+
+  const lines = []
+
+  // 1. Problem statement
+  lines.push('### Problem')
+  if (body) {
+    lines.push(body)
+  } else {
+    lines.push(`Implementation required for: ${title}`)
+  }
+  lines.push('')
+
+  // 2. Solution description
+  lines.push('### Solution')
+  if (task?.spec) {
+    // Extract key sections or summary from spec if present
+    const specLines = task.spec.split('\n')
+    const solutionLines = specLines.filter((l) => !l.startsWith('# Technical Specification') && !l.startsWith('## 1.'))
+    lines.push(solutionLines.slice(0, 15).join('\n').trim())
+  } else if (Array.isArray(task?.plan?.items) && task.plan.items.length > 0) {
+    lines.push('Implemented following plan:')
+    for (const item of task.plan.items) {
+      lines.push(`- ${item}`)
+    }
+  } else {
+    lines.push(`- Resolved requirements specified in ${title}`)
+  }
+  lines.push('')
+
+  // 3. Changed components & diff statistics
+  if (diffStats && (diffStats.files?.length > 0 || diffStats.filesChanged > 0)) {
+    lines.push('### Changed Components & Files')
+    lines.push(`- Total files changed: ${diffStats.filesChanged || diffStats.files.length}`)
+    if (diffStats.additions || diffStats.deletions) {
+      lines.push(`- Changes: +${diffStats.additions} / -${diffStats.deletions}`)
+    }
+    if (Array.isArray(diffStats.files) && diffStats.files.length > 0) {
+      for (const f of diffStats.files.slice(0, 12)) {
+        lines.push(`  - \`${f.path}\``)
+      }
+      if (diffStats.files.length > 12) {
+        lines.push(`  - ... and ${diffStats.files.length - 12} more files`)
+      }
+    }
+    lines.push('')
+  }
+
+  // 4. Commits list
+  if (Array.isArray(commits) && commits.length > 0) {
+    lines.push('### Commits')
+    for (const c of commits) {
+      const shaShort = c.sha ? `\`${c.sha.slice(0, 7)}\` ` : ''
+      lines.push(`- ${shaShort}${c.message}`)
+    }
+    lines.push('')
+  }
+
+  // 5. Verification status
+  const ver = verification || task?.report?.verification
+  if (ver) {
+    lines.push('### Verification Results')
+    const statusText = ver.status === 'passed' ? '✓ Tests Passed' : (ver.status === 'failed' ? '✗ Tests Failed' : 'Pending')
+    lines.push(`- Status: **${statusText}**`)
+    if (ver.command) {
+      lines.push(`- Command: \`${ver.command}\``)
+    }
+    if (ver.verifiedAt) {
+      lines.push(`- Timestamp: ${new Date(ver.verifiedAt).toISOString()}`)
+    }
+    lines.push('')
+  }
+
+  // 6. Issue reference closure
+  if (issueRef) {
+    lines.push(issueRef)
+  }
+
+  return lines.join('\n').trim()
+}
+
+/**
+ * Generate release notes entry for CHANGELOG.md.
+ *
+ * @param {object} params
+ * @param {object} params.task
+ * @param {Array<{ sha: string, message: string }>} [params.commits]
+ * @returns {string} Formatted release notes bullet
+ */
+export function generateReleaseNotes({ task, commits = [] }) {
+  const title = String(task?.title ?? '').trim()
+  const issueNum = typeof task?.issueNumber === 'number' ? ` (#${task.issueNumber})` : ''
+  const cleanTitle = title.replace(/^[A-Z]:\s*(Feature|Bug|Fix|Refactor|Task):\s*/i, '')
+
+  const lines = [`- **${cleanTitle}${issueNum}**:`]
+
+  if (Array.isArray(commits) && commits.length > 0) {
+    for (const c of commits.slice(0, 5)) {
+      lines.push(`  - ${c.message}`)
+    }
+  } else {
+    lines.push(`  - Implementation and automated verification complete.`)
+  }
+
+  return lines.join('\n')
+}

package/lib/routes/task-actions.js

@@ -1,4 +1,7 @@
 import { isTimeMachineAvailable, listTaskSnapshots, createCheckpointSnapshot, rollbackToSnapshot } from '../time-machine.js'
+import { generateTechnicalSpec, parseSpecMarkdown } from '../plan-generator.js'
+import { generatePrTitle, generatePrDescription, generateReleaseNotes } from '../pr-generator.js'
+import { getTaskCommits, getTaskDiffInspector } from '../worktree.js'
 
 /**
  * Extended actions for task route handlers (comments, reports, checklist, triage, subtasks, PR, nudge).
@@ -251,7 +254,7 @@ export async function handleCreateTaskPr({ store, gitea, task, input }) {
   if (!head) return { status: 400, body: { error: 'branch-required' } }
   const base = String(input?.base || 'main').trim()
   const title = String(input?.title || task.title || `PR: ${task.title}`).trim()
-  const body = String(input?.body || (task.issueNumber ? `Closes #${task.issueNumber}` : '')).trim()
+  const body = String(input?.body || task.prDescription || (task.issueNumber ? `Closes #${task.issueNumber}` : '')).trim()
 
   try {
     const pr = await gitea.createPullRequest({
@@ -416,3 +419,86 @@ export async function handleTaskRollbackSnapshot({ ctx, store, id, body, config,
     },
   }
 }
+
+
+/**
+ * Generate technical specification & plan for task (#376).
+ */
+export async function handleTaskGeneratePlan({ store, id, body, eventHub }) {
+  const task = store.getTask(id)
+  if (!task) return { status: 404, body: { error: 'task-not-found' } }
+
+  const result = generateTechnicalSpec(task, body?.options || {})
+  const updated = store.updateTask(id, {
+    spec: result.spec,
+    plan: { items: result.items, current: 0 },
+  })
+
+  if (eventHub && typeof eventHub.broadcast === 'function') {
+    eventHub.broadcast('task:change', { taskId: id, action: 'plan-generated', spec: result.spec })
+  }
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      spec: result.spec,
+      items: result.items,
+      summary: result.summary,
+      task: updated,
+    },
+  }
+}
+
+/**
+ * Handle PR description generation and saving (#379).
+ */
+export async function handleTaskPrDescription({ store, id, method, body, gitRunner }) {
+  const task = store.getTask(id)
+  if (!task) return { status: 404, body: { error: 'task-not-found' } }
+
+  if (method === 'POST' && typeof body?.prDescription === 'string') {
+    const updated = store.updateTask(id, { prDescription: body.prDescription })
+    return { status: 200, body: { success: true, prDescription: body.prDescription, task: updated } }
+  }
+
+  let commits = []
+  let diffStats = null
+
+  if (task.worktree) {
+    try {
+      commits = await getTaskCommits({ worktreePath: task.worktree, gitRunner })
+    } catch {
+      commits = []
+    }
+    try {
+      const inspector = await getTaskDiffInspector({ worktreePath: task.worktree, gitRunner })
+      if (inspector) {
+        diffStats = {
+          filesChanged: inspector.filesChanged || (inspector.files || []).length,
+          files: (inspector.files || []).map((f) => ({ path: f.file || f.path || f, changes: '' })),
+        }
+      }
+    } catch {
+      diffStats = null
+    }
+  }
+
+  const generatedTitle = generatePrTitle(task, commits)
+  const generatedDescription = generatePrDescription({ task, commits, diffStats })
+  const releaseNotes = generateReleaseNotes({ task, commits })
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      title: generatedTitle,
+      prDescription: task.prDescription || generatedDescription,
+      generatedDescription,
+      releaseNotes,
+      commits,
+      diffStats,
+    },
+  }
+}
+

package/lib/routes.js

@@ -71,4 +71,6 @@ export {
   handleTaskNudge,
   handleTaskSnapshot,
   handleTaskRollbackSnapshot,
+  handleTaskGeneratePlan,
+  handleTaskPrDescription,
 } from './routes/task-actions.js'