@thxgg/steward 0.1.0

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@thxgg/steward",
+  "version": "0.1.0",
+  "description": "Local-first PRD workflow steward with codemode MCP and web UI.",
+  "type": "module",
+  "author": "thxgg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thxgg/prd-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thxgg/prd-viewer/issues"
+  },
+  "homepage": "https://github.com/thxgg/prd-viewer#readme",
+  "keywords": [
+    "prd",
+    "mcp",
+    "workflow",
+    "nuxt",
+    "sqlite",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=22.6.0",
+    "npm": ">=10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "prd": "./bin/prd"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "app/",
+    "server/",
+    "public/",
+    "docs/MCP.md",
+    "nuxt.config.ts",
+    "components.json",
+    ".env.example",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "npm run build:host && nuxt build",
+    "build:host": "tsc -p tsconfig.host.build.json",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "mcp": "npm run build:host && node ./bin/prd mcp",
+    "ui": "npm run build:host && node ./bin/prd ui",
+    "typecheck": "nuxt typecheck && npm run typecheck:host",
+    "typecheck:host": "tsc -p tsconfig.host.json",
+    "prepack": "npm run build:host"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@vueuse/core": "^14.1.0",
+    "chokidar": "^5.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dompurify": "^3.3.1",
+    "lucide-vue-next": "^0.563.0",
+    "marked": "^17.0.1",
+    "nuxt": "^3.21.0",
+    "reka-ui": "^2.7.0",
+    "shiki": "^3.21.0",
+    "tailwind-merge": "^3.4.0",
+    "vue": "latest",
+    "vue-sonner": "^1.3.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@nuxtjs/color-mode": "^4.0.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/dompurify": "^3.2.0",
+    "@types/node": "^25.0.10",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.9.2",
+    "tw-animate-css": "^1.4.0",
+    "vue-tsc": "^3.2.3"
+  }
+}

package/public/robots.txt

@@ -0,0 +1 @@
+

package/server/api/browse.get.ts

@@ -0,0 +1,52 @@
+import { readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+  let path = (query.path as string) || homedir()
+
+  // Expand ~ to home directory
+  if (path.startsWith('~')) {
+    path = path.replace('~', homedir())
+  }
+
+  try {
+    const stats = await stat(path)
+    if (!stats.isDirectory()) {
+      throw createError({
+        statusCode: 400,
+        message: 'Path is not a directory'
+      })
+    }
+
+    const entries = await readdir(path, { withFileTypes: true })
+    const directories = entries
+      .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
+      .map(entry => ({
+        name: entry.name,
+        path: join(path, entry.name)
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name))
+
+    return {
+      current: path,
+      parent: join(path, '..'),
+      directories
+    }
+  } catch (err: any) {
+    if (err.code === 'ENOENT') {
+      throw createError({
+        statusCode: 404,
+        message: 'Directory not found'
+      })
+    }
+    if (err.code === 'EACCES') {
+      throw createError({
+        statusCode: 403,
+        message: 'Permission denied'
+      })
+    }
+    throw err
+  }
+})

package/server/api/repos/[repoId]/git/commits.get.ts

@@ -0,0 +1,103 @@
+import { getRepos } from '~~/server/utils/repos'
+import { isGitRepo, getCommitInfo } from '~~/server/utils/git'
+import type { GitCommit } from '~/types/git'
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+
+  if (!repoId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Repository ID is required',
+    })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Repository not found',
+    })
+  }
+
+  // Get query parameters
+  const query = getQuery(event)
+  const shasParam = query.shas as string | undefined
+  const repoPath = query.repo as string | undefined
+
+  if (!shasParam) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'shas query parameter is required',
+    })
+  }
+
+  const shas = shasParam.split(',').map(s => s.trim()).filter(Boolean)
+
+  if (shas.length === 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'At least one SHA is required',
+    })
+  }
+
+  // Resolve the git repo path
+  let gitRepoPath = repo.path
+
+  if (repoPath) {
+    // Validate that repoPath is within discovered gitRepos
+    if (!repo.gitRepos || repo.gitRepos.length === 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: 'repo parameter provided but no git repos discovered in this repository',
+      })
+    }
+
+    const matchedRepo = repo.gitRepos.find(gr => gr.relativePath === repoPath)
+    if (!matchedRepo) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `repo "${repoPath}" is not a discovered git repo. Available: ${repo.gitRepos.map(gr => gr.relativePath).join(', ')}`,
+      })
+    }
+
+    gitRepoPath = matchedRepo.absolutePath
+  }
+
+  // Check if resolved path is a git repository
+  if (!await isGitRepo(gitRepoPath)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Resolved path is not a git repository',
+    })
+  }
+
+  // Fetch commit info for each SHA
+  const commits: GitCommit[] = []
+  const errors: string[] = []
+
+  for (const sha of shas) {
+    try {
+      const commit = await getCommitInfo(gitRepoPath, sha)
+      // Add repoPath to the response
+      commits.push({
+        ...commit,
+        repoPath: repoPath || '',
+      })
+    } catch (error) {
+      errors.push(`${sha}: ${(error as Error).message}`)
+    }
+  }
+
+  // If all commits failed, throw error
+  if (commits.length === 0 && errors.length > 0) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `No valid commits found: ${errors.join('; ')}`,
+    })
+  }
+
+  return commits
+})

package/server/api/repos/[repoId]/git/diff.get.ts

@@ -0,0 +1,77 @@
+import { join } from 'node:path'
+import { getRepos } from '~~/server/utils/repos'
+import { isGitRepo, getCommitDiff } from '~~/server/utils/git'
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+
+  if (!repoId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Repository ID is required',
+    })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Repository not found',
+    })
+  }
+
+  // Get query parameters
+  const query = getQuery(event)
+  const commit = query.commit as string | undefined
+  const repoPath = query.repo as string | undefined
+
+  if (!commit) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'commit query parameter is required',
+    })
+  }
+
+  // Resolve the git repo path
+  let gitRepoPath = repo.path
+
+  if (repoPath) {
+    // Validate that repoPath is within discovered gitRepos
+    if (!repo.gitRepos || repo.gitRepos.length === 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: 'repo parameter provided but no git repos discovered in this repository',
+      })
+    }
+
+    const matchedRepo = repo.gitRepos.find(gr => gr.relativePath === repoPath)
+    if (!matchedRepo) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `repo "${repoPath}" is not a discovered git repo. Available: ${repo.gitRepos.map(gr => gr.relativePath).join(', ')}`,
+      })
+    }
+
+    gitRepoPath = matchedRepo.absolutePath
+  }
+
+  // Check if resolved path is a git repository
+  if (!await isGitRepo(gitRepoPath)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Resolved path is not a git repository',
+    })
+  }
+
+  try {
+    const files = await getCommitDiff(gitRepoPath, commit)
+    return files
+  } catch (error) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `Commit not found or invalid: ${(error as Error).message}`,
+    })
+  }
+})

package/server/api/repos/[repoId]/git/file-content.get.ts

@@ -0,0 +1,66 @@
+import { getRepos } from '~~/server/utils/repos'
+import { isGitRepo, getFileContent } from '~~/server/utils/git'
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+  const query = getQuery(event)
+  const commit = query.commit as string | undefined
+  const file = query.file as string | undefined
+  const repoPath = query.repo as string | undefined
+
+  if (!repoId) {
+    throw createError({ statusCode: 400, message: 'Repository ID is required' })
+  }
+
+  if (!commit) {
+    throw createError({ statusCode: 400, message: 'Commit SHA is required' })
+  }
+
+  if (!file) {
+    throw createError({ statusCode: 400, message: 'File path is required' })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({ statusCode: 404, message: 'Repository not found' })
+  }
+
+  // Resolve the git repo path
+  let gitRepoPath = repo.path
+
+  if (repoPath) {
+    // Validate that repoPath is within discovered gitRepos
+    if (!repo.gitRepos || repo.gitRepos.length === 0) {
+      throw createError({
+        statusCode: 400,
+        message: 'repo parameter provided but no git repos discovered in this repository',
+      })
+    }
+
+    const matchedRepo = repo.gitRepos.find(gr => gr.relativePath === repoPath)
+    if (!matchedRepo) {
+      throw createError({
+        statusCode: 400,
+        message: `repo "${repoPath}" is not a discovered git repo. Available: ${repo.gitRepos.map(gr => gr.relativePath).join(', ')}`,
+      })
+    }
+
+    gitRepoPath = matchedRepo.absolutePath
+  }
+
+  if (!await isGitRepo(gitRepoPath)) {
+    throw createError({ statusCode: 400, message: 'Not a git repository' })
+  }
+
+  try {
+    const content = await getFileContent(gitRepoPath, commit, file)
+    return { content }
+  } catch (error) {
+    throw createError({
+      statusCode: 404,
+      message: error instanceof Error ? error.message : 'Failed to get file content'
+    })
+  }
+})

package/server/api/repos/[repoId]/git/file-diff.get.ts

@@ -0,0 +1,109 @@
+import { getRepos } from '~~/server/utils/repos'
+import { isGitRepo, getFileDiff, validatePathInRepo } from '~~/server/utils/git'
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+
+  if (!repoId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Repository ID is required',
+    })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Repository not found',
+    })
+  }
+
+  // Get query parameters
+  const query = getQuery(event)
+  const commit = query.commit as string | undefined
+  const file = query.file as string | undefined
+  const repoPath = query.repo as string | undefined
+
+  if (!commit) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'commit query parameter is required',
+    })
+  }
+
+  if (!file) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'file query parameter is required',
+    })
+  }
+
+  // Resolve the git repo path
+  let gitRepoPath = repo.path
+
+  if (repoPath) {
+    // Validate that repoPath is within discovered gitRepos
+    if (!repo.gitRepos || repo.gitRepos.length === 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: 'repo parameter provided but no git repos discovered in this repository',
+      })
+    }
+
+    const matchedRepo = repo.gitRepos.find(gr => gr.relativePath === repoPath)
+    if (!matchedRepo) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `repo "${repoPath}" is not a discovered git repo. Available: ${repo.gitRepos.map(gr => gr.relativePath).join(', ')}`,
+      })
+    }
+
+    gitRepoPath = matchedRepo.absolutePath
+  }
+
+  // Check if resolved path is a git repository
+  if (!await isGitRepo(gitRepoPath)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Resolved path is not a git repository',
+    })
+  }
+
+  // Validate file path is within repo
+  if (!validatePathInRepo(gitRepoPath, file)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Invalid file path: path traversal not allowed',
+    })
+  }
+
+  try {
+    const hunks = await getFileDiff(gitRepoPath, commit, file)
+    return hunks
+  } catch (error) {
+    const message = (error as Error).message
+
+    // Determine appropriate error code
+    if (message.includes('Invalid commit SHA')) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: message,
+      })
+    }
+
+    if (message.includes('outside repository')) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: message,
+      })
+    }
+
+    throw createError({
+      statusCode: 404,
+      statusMessage: `File not found in commit or commit invalid: ${message}`,
+    })
+  }
+})

package/server/api/repos/[repoId]/prd/[prdSlug]/progress.get.ts

@@ -0,0 +1,36 @@
+import { getRepos } from '~~/server/utils/repos'
+import { getPrdState, migrateLegacyStateForRepo } from '~~/server/utils/prd-state'
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+  const prdSlug = getRouterParam(event, 'prdSlug')
+
+  if (!repoId || !prdSlug) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Repository ID and PRD slug are required'
+    })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Repository not found'
+    })
+  }
+
+  await migrateLegacyStateForRepo(repo)
+
+  try {
+    const state = await getPrdState(repo.id, prdSlug)
+    return state?.progress ?? null
+  } catch (error) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: `Failed to read progress state: ${(error as Error).message}`
+    })
+  }
+})

package/server/api/repos/[repoId]/prd/[prdSlug]/tasks/[taskId]/commits.get.ts

@@ -0,0 +1,146 @@
+import { getRepos, saveRepos, discoverGitRepos } from '~~/server/utils/repos'
+import { getPrdState, migrateLegacyStateForRepo } from '~~/server/utils/prd-state'
+import { resolveCommitRepo } from '~~/server/utils/git'
+import type { ProgressFile, CommitRef } from '~/types/task'
+import type { RepoConfig } from '~/types/repo'
+
+/**
+ * Response format for resolved commits
+ */
+interface ResolvedCommitResponse {
+  sha: string
+  repo: string
+}
+
+export default defineEventHandler(async (event) => {
+  const repoId = getRouterParam(event, 'repoId')
+  const prdSlug = getRouterParam(event, 'prdSlug')
+  const taskId = getRouterParam(event, 'taskId')
+
+  if (!repoId || !prdSlug || !taskId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Repository ID, PRD slug, and task ID are required'
+    })
+  }
+
+  const repos = await getRepos()
+  const repo = repos.find(r => r.id === repoId)
+
+  if (!repo) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Repository not found'
+    })
+  }
+
+  await migrateLegacyStateForRepo(repo)
+
+  let progress: ProgressFile | null = null
+  try {
+    const state = await getPrdState(repo.id, prdSlug)
+    progress = state?.progress ?? null
+  } catch (error) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: `Failed to read progress state: ${(error as Error).message}`
+    })
+  }
+
+  if (!progress) {
+    return []
+  }
+
+  // Find task log entry matching taskId
+  const taskLog = progress.taskLogs.find(log => log.taskId === taskId)
+
+  if (!taskLog) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `Task "${taskId}" not found in progress state`
+    })
+  }
+
+  // No commits recorded
+  if (!taskLog.commits || taskLog.commits.length === 0) {
+    return []
+  }
+
+  // Resolve all commits to normalized format with repo context
+  const resolvedCommits: ResolvedCommitResponse[] = []
+  const failedEntries: (string | CommitRef)[] = []
+
+  // First pass: try to resolve commits with current repo config
+  for (const commitEntry of taskLog.commits) {
+    try {
+      const resolved = await resolveCommitRepo(repo, commitEntry)
+      resolvedCommits.push({
+        sha: resolved.sha,
+        repo: resolved.repoPath,
+      })
+    } catch {
+      failedEntries.push(commitEntry)
+    }
+  }
+
+  // If some commits failed and this is a pseudo-monorepo, try re-discovering git repos
+  if (failedEntries.length > 0) {
+    const newGitRepos = await discoverGitRepos(repo.path)
+
+    // Check if we discovered any new repos
+    const existingPaths = new Set((repo.gitRepos || []).map(gr => gr.relativePath))
+    const hasNewRepos = newGitRepos.some(gr => !existingPaths.has(gr.relativePath))
+
+    if (hasNewRepos) {
+      // Update repo config with newly discovered repos
+      const repos = await getRepos()
+      const repoIndex = repos.findIndex(r => r.id === repoId)
+      if (repoIndex !== -1) {
+        const updatedRepo: RepoConfig = {
+          ...repos[repoIndex]!,
+          gitRepos: newGitRepos.length > 0 ? newGitRepos : undefined,
+        }
+        repos[repoIndex] = updatedRepo
+        await saveRepos(repos)
+
+        // Retry failed commits with updated config
+        for (const commitEntry of failedEntries) {
+          try {
+            const resolved = await resolveCommitRepo(updatedRepo, commitEntry)
+            resolvedCommits.push({
+              sha: resolved.sha,
+              repo: resolved.repoPath,
+            })
+          } catch {
+            // Still failed after re-discovery, add with empty repo
+            const sha = typeof commitEntry === 'string' ? commitEntry : commitEntry.sha
+            resolvedCommits.push({
+              sha,
+              repo: '',
+            })
+          }
+        }
+      } else {
+        // Repo not found in list, add failed entries with empty repo
+        for (const commitEntry of failedEntries) {
+          const sha = typeof commitEntry === 'string' ? commitEntry : commitEntry.sha
+          resolvedCommits.push({
+            sha,
+            repo: '',
+          })
+        }
+      }
+    } else {
+      // No new repos discovered, add failed entries with empty repo
+      for (const commitEntry of failedEntries) {
+        const sha = typeof commitEntry === 'string' ? commitEntry : commitEntry.sha
+        resolvedCommits.push({
+          sha,
+          repo: '',
+        })
+      }
+    }
+  }
+
+  return resolvedCommits
+})