Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.1 KB
Raw Blame
/**
 * GSD (Get Stuff Done) Scanner Service
 *
 * Scans managed apps for .planning/ directories and parses GSD project state.
 * Provides concern analysis and phase tracking for the Chief of Staff GSD integration.
 */

import { readFile, readdir, stat } from 'fs/promises'
import { join } from 'path'
import { createHash } from 'crypto'
import { getActiveApps } from './apps.js'
import { resolveGsdPath } from './gsdPaths.js'

// 30-second TTL cache per app
const projectCache = new Map()
const CACHE_TTL = 30000

function getCached(key) {
  const entry = projectCache.get(key)
  if (entry && Date.now() - entry.ts < CACHE_TTL) return entry.data
  return null
}
function setCache(key, data) {
  projectCache.set(key, { data, ts: Date.now() })
}

// Severity mapping for CONCERNS.md sections
const SEVERITY_MAP = {
  'security considerations': 'CRITICAL',
  'known bugs': 'HIGH',
  'missing critical features': 'HIGH',
  'tech debt': 'MEDIUM',
  'performance': 'MEDIUM',
  'fragile areas': 'MEDIUM',
  'test coverage': 'MEDIUM',
  'dependencies at risk': 'LOW',
  'scaling limits': 'LOW'
}

/**
 * Generate a deterministic hash ID from section title and item text
 */
function hashId(section, text) {
  return createHash('md5').update(`${section}:${text}`).digest('hex').slice(0, 12)
}

/**
 * Safely read a file, returning null if it doesn't exist
 */
async function safeReadFile(repoPath, relativePath) {
  const filePath = await resolveGsdPath(repoPath, relativePath)
  if (!filePath) return null
  const content = await readFile(filePath, 'utf-8').catch(err => {
    if (err.code === 'ENOENT') return null
    throw err
  })
  return content
}

/**
 * Safely stat a path, returning null if it doesn't exist
 */
async function safeStat(path) {
  return stat(path).catch(err => {
    if (err.code === 'ENOENT') return null
    throw err
  })
}

/**
 * Scan all active apps for .planning/ directories
 * Returns array of project summaries
 */
export async function scanForGsdProjects() {
  const apps = await getActiveApps()
  const projects = []

  for (const app of apps) {
    if (!app.repoPath) continue
    const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
    if (!planningPath) continue
    const planningInfo = await safeStat(planningPath)

    if (planningInfo?.isDirectory()) {
      const roadmapInfo = await safeStat(await resolveGsdPath(app.repoPath, 'ROADMAP.md'))
      const stateInfo = await safeStat(await resolveGsdPath(app.repoPath, 'STATE.md'))
      const concernsInfo = await safeStat(await resolveGsdPath(app.repoPath, 'CONCERNS.md'))

      projects.push({
        appId: app.id,
        appName: app.name,
        repoPath: app.repoPath,
        planningPath,
        hasRoadmap: !!roadmapInfo,
        hasState: !!stateInfo,
        hasConcerns: !!concernsInfo
      })
    }
  }

  console.log(`📋 GSD scan found ${projects.length} projects with .planning/`)
  return projects
}

/**
 * Parse ROADMAP.md to extract milestone table rows
 */
export async function parseRoadmapMd(repoPath, relativePath) {
  const content = await safeReadFile(repoPath, relativePath)
  if (!content) return null

  const milestones = []
  const lines = content.split('\n')

  for (const line of lines) {
    if (!line.startsWith('|')) continue
    // Skip header separator rows (e.g., |---|---|---|)
    if (/^\|[\s-]+\|/.test(line) && !line.match(/[a-zA-Z0-9]/)) continue
    // Skip header rows
    if (line.toLowerCase().includes('phase') && line.toLowerCase().includes('title')) continue

    const cells = line.split('|').map(c => c.trim()).filter(Boolean)
    if (cells.length >= 3) {
      milestones.push({
        phase: cells[0],
        title: cells[1],
        status: cells[2]
      })
    }
  }

  return { milestones, raw: content }
}

/**
 * Parse STATE.md to extract YAML frontmatter
 */
export async function parseStateMd(repoPath, relativePath) {
  const content = await safeReadFile(repoPath, relativePath)
  if (!content) return null

  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
  if (!frontmatterMatch) return { frontmatter: {}, raw: content }

  const frontmatter = {}
  const lines = frontmatterMatch[1].split('\n')
  for (const line of lines) {
    const colonIdx = line.indexOf(':')
    if (colonIdx === -1) continue
    const key = line.slice(0, colonIdx).trim()
    const value = line.slice(colonIdx + 1).trim()
    if (key) frontmatter[key] = value
  }

  return { frontmatter, raw: content }
}

/**
 * Parse CONCERNS.md to extract sections with severity
 */
export async function parseConcernsMd(repoPath, relativePath) {
  const content = await safeReadFile(repoPath, relativePath)
  if (!content) return null

  const sections = []
  let currentSection = null
  const lines = content.split('\n')

  for (const line of lines) {
    const headerMatch = line.match(/^##\s+(.+)/)
    if (headerMatch) {
      currentSection = {
        title: headerMatch[1].trim(),
        severity: 'MEDIUM',
        items: []
      }
      // Map severity based on section title
      const lowerTitle = currentSection.title.toLowerCase()
      for (const [pattern, severity] of Object.entries(SEVERITY_MAP)) {
        if (lowerTitle.includes(pattern)) {
          currentSection.severity = severity
          break
        }
      }
      sections.push(currentSection)
      continue
    }

    if (currentSection) {
      const itemMatch = line.match(/^-\s+(.+)/)
      if (itemMatch) {
        const text = itemMatch[1].trim()
        currentSection.items.push({
          id: hashId(currentSection.title, text),
          text
        })
      }
    }
  }

  return { sections }
}

/**
 * Parse a single PLAN.md file content into frontmatter + tasks
 */
function parsePlanContent(content) {
  const frontmatter = {}
  let bodyContent = content

  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
  if (frontmatterMatch) {
    const fmLines = frontmatterMatch[1].split('\n')
    for (const line of fmLines) {
      const colonIdx = line.indexOf(':')
      if (colonIdx === -1) continue
      const key = line.slice(0, colonIdx).trim()
      const value = line.slice(colonIdx + 1).trim()
      if (key) frontmatter[key] = value
    }
    bodyContent = content.slice(frontmatterMatch[0].length)
  }

  const tasks = []
  for (const line of bodyContent.split('\n')) {
    const taskMatch = line.match(/^[-*]\s+\[([ xX])\]\s+(.+)/)
    if (taskMatch) {
      tasks.push({
        completed: taskMatch[1].toLowerCase() === 'x',
        text: taskMatch[2].trim()
      })
    }
  }

  return { frontmatter, tasks, raw: content }
}

/**
 * Scan phase directory for *-PLAN.md files (e.g. 01-01-PLAN.md, 03-02-PLAN.md)
 * Returns array of sub-plans sorted by filename
 */
export async function parsePhasePlans(repoPath, relativePath) {
  const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
  const entries = await readdir(phasePath).catch(() => [])
  const planFiles = entries.filter(f => f.endsWith('-PLAN.md')).sort()
  if (planFiles.length === 0) return []

  const plans = []
  for (const filename of planFiles) {
    const content = await safeReadFile(repoPath, join(relativePath, filename))
    if (!content) continue
    plans.push({ filename, ...parsePlanContent(content) })
  }
  return plans
}

/**
 * Parse SUMMARY.md files in a phase directory
 */
export async function parsePhaseSummaries(repoPath, relativePath) {
  const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
  const entries = await readdir(phasePath).catch(() => [])
  const summaryFiles = entries.filter(f => f.endsWith('-SUMMARY.md')).sort()
  if (summaryFiles.length === 0) return []

  const summaries = []
  for (const filename of summaryFiles) {
    const content = await safeReadFile(repoPath, join(relativePath, filename))
    if (!content) continue
    summaries.push({ filename, ...parsePlanContent(content) })
  }
  return summaries
}

/**
 * Scan phase directory for *-VERIFICATION.md (e.g. 01-VERIFICATION.md)
 */
export async function parseVerification(repoPath, relativePath) {
  const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
  const entries = await readdir(phasePath).catch(() => [])
  const verifyFile = entries.find(f => f.endsWith('-VERIFICATION.md'))
  if (!verifyFile) return null

  const content = await safeReadFile(repoPath, join(relativePath, verifyFile))
  if (!content) return null

  let status = 'unknown'
  let score = null

  const statusMatch = content.match(/status:\s*(\w+)/i)
  if (statusMatch) status = statusMatch[1].toLowerCase()

  const scoreMatch = content.match(/score:\s*([\d.]+)/i)
  if (scoreMatch) score = parseFloat(scoreMatch[1])

  return { status, score, raw: content }
}

/**
 * Scan phase directory for *-RESEARCH.md (e.g. 01-RESEARCH.md)
 */
export async function parsePhaseResearch(repoPath, relativePath) {
  const phasePath = await resolveGsdPath(repoPath, relativePath, 'dir')
  const entries = await readdir(phasePath).catch(() => [])
  const researchFile = entries.find(f => f.endsWith('-RESEARCH.md'))
  if (!researchFile) return null

  const content = await safeReadFile(repoPath, join(relativePath, researchFile))
  if (!content) return null
  return { filename: researchFile, raw: content }
}

/**
 * Get full GSD project state for a single app
 */
export async function getGsdProject(appIdOrPath) {
  const cached = getCached(`project:${appIdOrPath}`)
  if (cached) return cached

  const apps = await getActiveApps()
  const app = apps.find(a => a.id === appIdOrPath || a.repoPath === appIdOrPath)
  if (!app) return null

  const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
  if (!planningPath) return null
  const planningInfo = await safeStat(planningPath)
  if (!planningInfo?.isDirectory()) return null

  const roadmap = await parseRoadmapMd(app.repoPath, 'ROADMAP.md')
  const state = await parseStateMd(app.repoPath, 'STATE.md')
  const concerns = await parseConcernsMd(app.repoPath, 'CONCERNS.md')
  const projectDoc = await safeReadFile(app.repoPath, 'PROJECT.md')

  // Scan for phase directories
  const phases = []
  const phasesDir = await resolveGsdPath(app.repoPath, 'phases', 'dir')
  const phasesDirInfo = await safeStat(phasesDir)
  if (phasesDirInfo?.isDirectory()) {
    const entries = await readdir(phasesDir, { withFileTypes: true })
    for (const entry of entries) {
      if (!entry.isDirectory()) continue
      const phasePath = join('phases', entry.name)
      const plans = await parsePhasePlans(app.repoPath, phasePath)
      const summaries = await parsePhaseSummaries(app.repoPath, phasePath)
      const verification = await parseVerification(app.repoPath, phasePath)
      const research = await parsePhaseResearch(app.repoPath, phasePath)
      const totalTasks = plans.reduce((sum, p) => sum + p.tasks.length, 0)
      const completedTasks = plans.reduce((sum, p) => sum + p.tasks.filter(t => t.completed).length, 0)
      phases.push({
        id: entry.name,
        plans,
        summaries,
        verification,
        research,
        totalTasks,
        completedTasks
      })
    }
    phases.sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }))
  }

  // Read config if present
  const configContent = await safeReadFile(app.repoPath, 'config.json')
  const config = configContent ? JSON.parse(configContent) : null

  const result = {
    app: { id: app.id, name: app.name, repoPath: app.repoPath },
    roadmap,
    state,
    concerns,
    projectDoc: projectDoc ? { raw: projectDoc } : null,
    phases,
    config
  }

  setCache(`project:${appIdOrPath}`, result)
  return result
}

/**
 * Analyze project state to find phases ready to advance
 */
export async function getGsdPendingActions(appId) {
  const project = await getGsdProject(appId)
  if (!project) return []

  const actions = []
  const _currentPhase = project.state?.frontmatter?.current_phase

  for (const phase of project.phases) {
    const hasPlans = phase.plans?.length > 0
    const hasVerification = !!phase.verification
    const allTasksComplete = phase.totalTasks > 0 && phase.completedTasks === phase.totalTasks
    const verificationPassed = phase.verification?.status === 'passed'

    let nextAction = null
    if (!hasPlans) {
      nextAction = 'plan'
    } else if (!allTasksComplete) {
      nextAction = 'execute'
    } else if (!hasVerification || !verificationPassed) {
      nextAction = 'verify'
    }

    if (nextAction) {
      actions.push({
        phaseId: phase.id,
        currentStep: hasPlans ? (allTasksComplete ? 'executed' : 'planned') : 'unplanned',
        nextAction
      })
    }
  }

  return actions
}

/**
 * Generate CoS task objects from CONCERNS.md items
 */
export async function generateConcernTasks(appId) {
  const project = await getGsdProject(appId)
  if (!project?.concerns) return []

  const tasks = []
  for (const section of project.concerns.sections) {
    for (const item of section.items) {
      tasks.push({
        id: `gsd-concern-${item.id}`,
        description: `[GSD:Concern] ${section.title}: ${item.text}`,
        priority: section.severity === 'CRITICAL' ? 'HIGH' : section.severity,
        metadata: {
          gsdConcern: item.id,
          gsdSourceFile: 'CONCERNS.md',
          gsdSection: section.title,
          gsdSeverity: section.severity,
          app: project.app.id
        },
        taskType: 'internal'
      })
    }
  }

  return tasks
}