@thxgg/steward 0.1.0

package/server/utils/prd-state.ts

@@ -0,0 +1,335 @@
+import { promises as fs } from 'node:fs'
+import { join } from 'node:path'
+import type { RepoConfig } from '../../app/types/repo.js'
+import type { TasksFile, ProgressFile } from '../../app/types/task.js'
+import { dbAll, dbGet, dbRun } from './db.js'
+
+type PrdStateRow = {
+  repo_id: string
+  slug: string
+  tasks_json: string | null
+  progress_json: string | null
+  notes_md: string | null
+  updated_at: string
+}
+
+export type StoredPrdState = {
+  slug: string
+  tasks: TasksFile | null
+  progress: ProgressFile | null
+  notes: string | null
+  updatedAt: string
+}
+
+export type PrdStateUpdate = {
+  tasks?: TasksFile | null
+  progress?: ProgressFile | null
+  notes?: string | null
+}
+
+export type PrdStateSummary = {
+  hasState: boolean
+  taskCount?: number
+  completedCount?: number
+}
+
+const LEGACY_STATE_STABLE_MS = 0
+const migrationInFlight = new Map<string, Promise<void>>()
+const cleanupCompletedRepoIds = new Set<string>()
+
+function parseStoredJson<T>(raw: string | null, fieldName: string): T | null {
+  if (!raw) {
+    return null
+  }
+
+  try {
+    return JSON.parse(raw) as T
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid JSON stored in ${fieldName}: ${message}`)
+  }
+}
+
+function getTaskCounts(tasksFile: TasksFile): { taskCount: number; completedCount: number } | null {
+  if (!tasksFile || !Array.isArray(tasksFile.tasks)) {
+    return null
+  }
+
+  const taskCount = tasksFile.tasks.length
+  const completedCount = tasksFile.tasks.filter(task => task.status === 'completed').length
+  return { taskCount, completedCount }
+}
+
+function normalizeLegacyTasksFile(tasksFile: TasksFile | null): TasksFile | null {
+  if (!tasksFile || !Array.isArray(tasksFile.tasks)) {
+    return tasksFile
+  }
+
+  const tasks = tasksFile.tasks.map((task) => {
+    const passes = (task as { passes?: unknown }).passes
+    if (Array.isArray(passes)) {
+      return task
+    }
+
+    return {
+      ...task,
+      passes: []
+    }
+  })
+
+  return {
+    ...tasksFile,
+    tasks
+  }
+}
+
+export async function getPrdState(repoId: string, slug: string): Promise<StoredPrdState | null> {
+  const row = await dbGet<PrdStateRow>(
+    `
+      SELECT repo_id, slug, tasks_json, progress_json, notes_md, updated_at
+      FROM prd_states
+      WHERE repo_id = ? AND slug = ?
+    `,
+    [repoId, slug]
+  )
+
+  if (!row) {
+    return null
+  }
+
+  const tasks = normalizeLegacyTasksFile(parseStoredJson<TasksFile>(row.tasks_json, 'prd_states.tasks_json'))
+
+  return {
+    slug: row.slug,
+    tasks,
+    progress: parseStoredJson<ProgressFile>(row.progress_json, 'prd_states.progress_json'),
+    notes: row.notes_md,
+    updatedAt: row.updated_at
+  }
+}
+
+export async function getPrdStateSummaries(repoId: string): Promise<Map<string, PrdStateSummary>> {
+  const rows = await dbAll<Pick<PrdStateRow, 'slug' | 'tasks_json'>>(
+    'SELECT slug, tasks_json FROM prd_states WHERE repo_id = ?',
+    [repoId]
+  )
+
+  const summaries = new Map<string, PrdStateSummary>()
+
+  for (const row of rows) {
+    const summary: PrdStateSummary = { hasState: true }
+
+    if (row.tasks_json) {
+      try {
+        const tasksFile = JSON.parse(row.tasks_json) as TasksFile
+        const counts = getTaskCounts(tasksFile)
+        if (counts) {
+          summary.taskCount = counts.taskCount
+          summary.completedCount = counts.completedCount
+        }
+      } catch {
+        // Keep hasState=true and omit counts when JSON is malformed.
+      }
+    }
+
+    summaries.set(row.slug, summary)
+  }
+
+  return summaries
+}
+
+export async function upsertPrdState(repoId: string, slug: string, update: PrdStateUpdate): Promise<void> {
+  const existing = await dbGet<PrdStateRow>(
+    `
+      SELECT repo_id, slug, tasks_json, progress_json, notes_md, updated_at
+      FROM prd_states
+      WHERE repo_id = ? AND slug = ?
+    `,
+    [repoId, slug]
+  )
+
+  const tasksJson = update.tasks === undefined
+    ? existing?.tasks_json ?? null
+    : (update.tasks === null ? null : JSON.stringify(update.tasks))
+
+  const progressJson = update.progress === undefined
+    ? existing?.progress_json ?? null
+    : (update.progress === null ? null : JSON.stringify(update.progress))
+
+  const notesMd = update.notes === undefined
+    ? existing?.notes_md ?? null
+    : update.notes
+
+  const updatedAt = new Date().toISOString()
+
+  if (existing) {
+    await dbRun(
+      `
+        UPDATE prd_states
+        SET tasks_json = ?, progress_json = ?, notes_md = ?, updated_at = ?
+        WHERE repo_id = ? AND slug = ?
+      `,
+      [tasksJson, progressJson, notesMd, updatedAt, repoId, slug]
+    )
+    return
+  }
+
+  await dbRun(
+    `
+      INSERT INTO prd_states (repo_id, slug, tasks_json, progress_json, notes_md, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `,
+    [repoId, slug, tasksJson, progressJson, notesMd, updatedAt]
+  )
+}
+
+type LegacyJsonReadResult<T> = {
+  value: T | null
+  imported: boolean
+}
+
+async function readStableLegacyFile(filePath: string, minFileAgeMs: number): Promise<string | null> {
+  try {
+    const stats = await fs.stat(filePath)
+    if (!stats.isFile()) {
+      return null
+    }
+
+    if (Date.now() - stats.mtimeMs < minFileAgeMs) {
+      return null
+    }
+
+    return await fs.readFile(filePath, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+async function readLegacyJsonFile<T>(
+  filePath: string,
+  label: string,
+  minFileAgeMs: number
+): Promise<LegacyJsonReadResult<T>> {
+  const content = await readStableLegacyFile(filePath, minFileAgeMs)
+  if (!content) {
+    return { value: null, imported: false }
+  }
+
+  try {
+    return { value: JSON.parse(content) as T, imported: true }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.warn(`[legacy-state] Skipping invalid ${label} at ${filePath}: ${message}`)
+    return { value: null, imported: false }
+  }
+}
+
+async function removeIfExists(filePath: string): Promise<void> {
+  try {
+    await fs.unlink(filePath)
+  } catch {
+    // File may already be removed.
+  }
+}
+
+async function removeDirIfEmpty(dirPath: string): Promise<void> {
+  try {
+    const entries = await fs.readdir(dirPath)
+    if (entries.length === 0) {
+      await fs.rmdir(dirPath)
+    }
+  } catch {
+    // Directory may not exist or may contain files.
+  }
+}
+
+async function runLegacyStateMigration(
+  repo: RepoConfig,
+  cleanupLegacyFiles: boolean,
+  minFileAgeMs: number
+): Promise<void> {
+  const legacyStateDir = join(repo.path, '.claude', 'state')
+
+  const entries = await fs.readdir(legacyStateDir, { withFileTypes: true, encoding: 'utf8' }).catch(() => null)
+  if (!entries) {
+    return
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue
+    }
+
+    const slug = entry.name
+    const slugDir = join(legacyStateDir, slug)
+    const tasksPath = join(slugDir, 'tasks.json')
+    const progressPath = join(slugDir, 'progress.json')
+    const notesPath = join(slugDir, 'notes.md')
+
+    const [tasksResult, progressResult, notesContent] = await Promise.all([
+      readLegacyJsonFile<TasksFile>(tasksPath, 'tasks.json', minFileAgeMs),
+      readLegacyJsonFile<ProgressFile>(progressPath, 'progress.json', minFileAgeMs),
+      readStableLegacyFile(notesPath, minFileAgeMs)
+    ])
+
+    const shouldImportNotes = notesContent !== null
+    const shouldImport = tasksResult.imported || progressResult.imported || shouldImportNotes
+
+    if (!shouldImport) {
+      continue
+    }
+
+    await upsertPrdState(repo.id, slug, {
+      ...(tasksResult.imported && { tasks: tasksResult.value }),
+      ...(progressResult.imported && { progress: progressResult.value }),
+      ...(shouldImportNotes && { notes: notesContent })
+    })
+
+    if (cleanupLegacyFiles) {
+      if (tasksResult.imported) {
+        await removeIfExists(tasksPath)
+      }
+
+      if (progressResult.imported) {
+        await removeIfExists(progressPath)
+      }
+
+      if (shouldImportNotes) {
+        await removeIfExists(notesPath)
+      }
+
+      await removeDirIfEmpty(slugDir)
+    }
+  }
+
+  if (cleanupLegacyFiles) {
+    await removeDirIfEmpty(legacyStateDir)
+  }
+}
+
+export async function migrateLegacyStateForRepo(
+  repo: RepoConfig,
+  options: { cleanupLegacyFiles?: boolean; minFileAgeMs?: number } = {}
+): Promise<void> {
+  const cleanupLegacyFiles = options.cleanupLegacyFiles
+    ?? !cleanupCompletedRepoIds.has(repo.id)
+  const minFileAgeMs = options.minFileAgeMs ?? LEGACY_STATE_STABLE_MS
+
+  const inFlight = migrationInFlight.get(repo.id)
+  if (inFlight) {
+    return inFlight
+  }
+
+  const migrationPromise = runLegacyStateMigration(repo, cleanupLegacyFiles, minFileAgeMs)
+    .then(() => {
+      if (cleanupLegacyFiles) {
+        cleanupCompletedRepoIds.add(repo.id)
+      }
+    })
+    .finally(() => {
+      migrationInFlight.delete(repo.id)
+    })
+
+  migrationInFlight.set(repo.id, migrationPromise)
+  return migrationPromise
+}

package/server/utils/repos.ts

@@ -0,0 +1,322 @@
+import { promises as fs } from 'node:fs'
+import { join, basename, resolve, relative } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { RepoConfig, GitRepoInfo } from '../../app/types/repo.js'
+import { dbAll, dbGet, dbRun } from './db.js'
+
+const LEGACY_REPOS_FILE = join(process.cwd(), 'server', 'data', 'repos.json')
+
+type RepoRow = {
+  id: string
+  name: string
+  path: string
+  added_at: string
+  git_repos_json: string | null
+}
+
+let legacyImportPromise: Promise<void> | null = null
+
+function serializeGitRepos(gitRepos?: GitRepoInfo[]): string | null {
+  return gitRepos && gitRepos.length > 0 ? JSON.stringify(gitRepos) : null
+}
+
+function parseGitRepos(gitReposJson: string | null): GitRepoInfo[] | undefined {
+  if (!gitReposJson) {
+    return undefined
+  }
+
+  try {
+    const parsed = JSON.parse(gitReposJson)
+    if (!Array.isArray(parsed)) {
+      return undefined
+    }
+
+    const validRepos = parsed.filter((item): item is GitRepoInfo => {
+      return !!item
+        && typeof item === 'object'
+        && typeof (item as { relativePath?: unknown }).relativePath === 'string'
+        && typeof (item as { absolutePath?: unknown }).absolutePath === 'string'
+        && typeof (item as { name?: unknown }).name === 'string'
+    })
+
+    return validRepos.length > 0 ? validRepos : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function rowToRepo(row: RepoRow): RepoConfig {
+  const gitRepos = parseGitRepos(row.git_repos_json)
+  return {
+    id: row.id,
+    name: row.name,
+    path: row.path,
+    addedAt: row.added_at,
+    ...(gitRepos && { gitRepos })
+  }
+}
+
+function isLegacyRepoConfig(value: unknown): value is RepoConfig {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const repo = value as Partial<RepoConfig>
+  return typeof repo.id === 'string'
+    && typeof repo.name === 'string'
+    && typeof repo.path === 'string'
+    && typeof repo.addedAt === 'string'
+}
+
+async function importLegacyReposIfNeeded(): Promise<void> {
+  if (legacyImportPromise) {
+    return legacyImportPromise
+  }
+
+  legacyImportPromise = (async () => {
+    const row = await dbGet<{ count: number }>('SELECT COUNT(*) as count FROM repos')
+    if ((row?.count ?? 0) > 0) {
+      return
+    }
+
+    let legacyRepos: unknown
+    try {
+      const content = await fs.readFile(LEGACY_REPOS_FILE, 'utf-8')
+      legacyRepos = JSON.parse(content)
+    } catch {
+      return
+    }
+
+    if (!Array.isArray(legacyRepos) || legacyRepos.length === 0) {
+      return
+    }
+
+    for (const candidate of legacyRepos) {
+      if (!isLegacyRepoConfig(candidate)) {
+        continue
+      }
+
+      const repo = candidate
+      await dbRun(
+        `
+          INSERT INTO repos (id, name, path, added_at, git_repos_json)
+          VALUES (?, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET
+            name = excluded.name,
+            path = excluded.path,
+            added_at = excluded.added_at,
+            git_repos_json = excluded.git_repos_json
+        `,
+        [repo.id, repo.name, repo.path, repo.addedAt, serializeGitRepos(repo.gitRepos)]
+      )
+    }
+
+    try {
+      await fs.unlink(LEGACY_REPOS_FILE)
+    } catch {
+      // Legacy file may not be removable; DB remains source of truth.
+    }
+  })()
+
+  return legacyImportPromise
+}
+
+export async function getRepos(): Promise<RepoConfig[]> {
+  await importLegacyReposIfNeeded()
+  const rows = await dbAll<RepoRow>('SELECT id, name, path, added_at, git_repos_json FROM repos ORDER BY added_at ASC')
+  return rows.map(rowToRepo)
+}
+
+export async function saveRepos(repos: RepoConfig[]): Promise<void> {
+  await importLegacyReposIfNeeded()
+
+  for (const repo of repos) {
+    await dbRun(
+      `
+        INSERT INTO repos (id, name, path, added_at, git_repos_json)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          name = excluded.name,
+          path = excluded.path,
+          added_at = excluded.added_at,
+          git_repos_json = excluded.git_repos_json
+      `,
+      [repo.id, repo.name, repo.path, repo.addedAt, serializeGitRepos(repo.gitRepos)]
+    )
+  }
+
+  if (repos.length === 0) {
+    await dbRun('DELETE FROM repos')
+    return
+  }
+
+  const repoIds = repos.map(repo => repo.id)
+  const placeholders = repoIds.map(() => '?').join(', ')
+  await dbRun(`DELETE FROM repos WHERE id NOT IN (${placeholders})`, repoIds)
+}
+
+export async function addRepo(path: string, name?: string): Promise<RepoConfig> {
+  await importLegacyReposIfNeeded()
+
+  const resolvedPath = resolve(path)
+
+  const existing = await dbGet<{ id: string }>('SELECT id FROM repos WHERE path = ?', [resolvedPath])
+  if (existing) {
+    throw new Error('Repository already added')
+  }
+
+  const gitRepos = await discoverGitRepos(resolvedPath)
+
+  const repo: RepoConfig = {
+    id: randomUUID(),
+    name: name || basename(resolvedPath),
+    path: resolvedPath,
+    addedAt: new Date().toISOString(),
+    ...(gitRepos.length > 0 && { gitRepos })
+  }
+
+  await dbRun(
+    'INSERT INTO repos (id, name, path, added_at, git_repos_json) VALUES (?, ?, ?, ?, ?)',
+    [repo.id, repo.name, repo.path, repo.addedAt, serializeGitRepos(repo.gitRepos)]
+  )
+
+  return repo
+}
+
+/**
+ * Get a repository by its ID
+ */
+export async function getRepoById(id: string): Promise<RepoConfig | undefined> {
+  await importLegacyReposIfNeeded()
+  const row = await dbGet<RepoRow>(
+    'SELECT id, name, path, added_at, git_repos_json FROM repos WHERE id = ?',
+    [id]
+  )
+  return row ? rowToRepo(row) : undefined
+}
+
+export async function removeRepo(id: string): Promise<boolean> {
+  await importLegacyReposIfNeeded()
+  const result = await dbRun('DELETE FROM repos WHERE id = ?', [id])
+  return result.changes > 0
+}
+
+/**
+ * Directories to skip when scanning for git repos
+ */
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'vendor',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  '__pycache__',
+  '.venv',
+  'venv',
+  'target', // Rust
+  'Pods', // iOS
+])
+
+/**
+ * Check if a directory contains a .git folder (is a git repository)
+ */
+async function isGitRepo(dirPath: string): Promise<boolean> {
+  try {
+    const gitPath = join(dirPath, '.git')
+    const stats = await fs.stat(gitPath)
+    return stats.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Discover git repositories within a directory up to a specified depth.
+ * Returns empty array if basePath itself is a git repo (standard case).
+ *
+ * @param basePath - The root directory to scan
+ * @param maxDepth - Maximum depth to scan (default: 2)
+ * @returns Array of discovered git repository info
+ */
+export async function discoverGitRepos(
+  basePath: string,
+  maxDepth: number = 2
+): Promise<GitRepoInfo[]> {
+  const resolvedBase = resolve(basePath)
+
+  // If basePath itself is a git repo, return empty (standard repo case)
+  if (await isGitRepo(resolvedBase)) {
+    return []
+  }
+
+  const discovered: GitRepoInfo[] = []
+
+  async function scanDirectory(dirPath: string, currentDepth: number): Promise<void> {
+    if (currentDepth > maxDepth) return
+
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true })
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        if (IGNORED_DIRS.has(entry.name)) continue
+
+        const fullPath = join(dirPath, entry.name)
+
+        // Check if this directory is a git repo
+        if (await isGitRepo(fullPath)) {
+          const relativePath = relative(resolvedBase, fullPath)
+          discovered.push({
+            relativePath,
+            absolutePath: fullPath,
+            name: entry.name,
+          })
+          // Don't scan inside git repos
+          continue
+        }
+
+        // Continue scanning subdirectories
+        await scanDirectory(fullPath, currentDepth + 1)
+      }
+    } catch {
+      // Permission denied or other errors - skip this directory
+    }
+  }
+
+  await scanDirectory(resolvedBase, 1)
+
+  return discovered
+}
+
+export async function validateRepoPath(path: string): Promise<{ valid: boolean; error?: string }> {
+  // Normalize the path
+  const resolvedPath = resolve(path)
+
+  // Ensure path is absolute (starts with / on Unix or drive letter on Windows)
+  if (!resolvedPath.startsWith('/') && !/^[A-Za-z]:/.test(resolvedPath)) {
+    return { valid: false, error: 'Path must be absolute' }
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath)
+    if (!stats.isDirectory()) {
+      return { valid: false, error: 'Path is not a directory' }
+    }
+
+    // Check if it looks like a valid repository (has docs/prd directory)
+    const hasPrdDir = await fs.stat(join(resolvedPath, 'docs', 'prd')).then(() => true).catch(() => false)
+
+    if (!hasPrdDir) {
+      return {
+        valid: false,
+        error: 'Directory does not appear to be a valid PRD repository (missing docs/prd directory)'
+      }
+    }
+
+    return { valid: true }
+  } catch {
+    return { valid: false, error: 'Directory does not exist' }
+  }
+}