@thxgg/steward 0.1.0

package/app/pages/index.vue

@@ -0,0 +1,257 @@
+<script setup lang="ts">
+import { FolderOpen, FileText, ArrowRight, Folder } from 'lucide-vue-next'
+import { Button } from '~/components/ui/button'
+import { Input } from '~/components/ui/input'
+
+const router = useRouter()
+const { repos, currentRepo, currentRepoId, addRepo, status: reposStatus } = useRepos()
+const { prds, prdsStatus } = usePrd()
+const { showSuccess } = useToast()
+
+// Onboarding state
+const newRepoPath = ref('')
+const addError = ref<string | null>(null)
+const isAdding = ref(false)
+
+// Directory browser state (reused from RepoSelector pattern)
+const showBrowser = ref(false)
+const browserPath = ref('')
+const browserDirs = ref<{ name: string; path: string }[]>([])
+const browserLoading = ref(false)
+
+async function browseDirectory(path?: string) {
+  browserLoading.value = true
+  try {
+    const data = await $fetch('/api/browse', {
+      query: { path: path || browserPath.value || undefined }
+    })
+    browserPath.value = data.current
+    browserDirs.value = data.directories
+  } catch {
+    // Silently fail - directory browser will show empty state
+  } finally {
+    browserLoading.value = false
+  }
+}
+
+function openBrowser() {
+  showBrowser.value = true
+  browseDirectory(newRepoPath.value || undefined)
+}
+
+function selectDirectory(path: string) {
+  newRepoPath.value = path
+  showBrowser.value = false
+  addError.value = null
+}
+
+function navigateUp() {
+  const parent = browserPath.value.split('/').slice(0, -1).join('/') || '/'
+  browseDirectory(parent)
+}
+
+async function handleAddRepo() {
+  if (!newRepoPath.value.trim()) {
+    addError.value = 'Please enter a repository path'
+    return
+  }
+
+  isAdding.value = true
+  addError.value = null
+
+  try {
+    const repo = await addRepo(newRepoPath.value.trim())
+    newRepoPath.value = ''
+    showSuccess('Repository added', repo?.name || 'Successfully added repository')
+  } catch (error) {
+    if (error instanceof Error) {
+      const fetchError = error as { data?: { message?: string } }
+      addError.value = fetchError.data?.message || error.message
+    } else {
+      addError.value = 'Failed to add repository'
+    }
+  } finally {
+    isAdding.value = false
+  }
+}
+
+// Determine what state we're in
+const showOnboarding = computed(() => {
+  return reposStatus.value !== 'pending' && (!repos.value || repos.value.length === 0)
+})
+
+const showSelectPrompt = computed(() => {
+  return repos.value && repos.value.length > 0 && !currentRepoId.value
+})
+
+const showWelcome = computed(() => {
+  return currentRepoId.value && (!prds.value || prds.value.length === 0)
+})
+
+const showPrdList = computed(() => {
+  return currentRepoId.value && prds.value && prds.value.length > 0
+})
+
+// Auto-navigate to first PRD when repo is selected and has documents
+watch(
+  [currentRepoId, prds, prdsStatus],
+  ([repoId, prdList, status]) => {
+    const firstPrd = prdList?.[0]
+    if (repoId && status === 'success' && firstPrd) {
+      router.push(`/${repoId}/${firstPrd.slug}`)
+    }
+  },
+  { immediate: true }
+)
+</script>
+
+<template>
+  <div class="flex h-full items-center justify-center p-6 md:p-8">
+    <!-- Onboarding: No repos configured -->
+    <div v-if="showOnboarding" class="mx-auto max-w-md text-center">
+      <div class="mx-auto mb-6 flex size-16 items-center justify-center rounded-full bg-primary/10">
+        <FolderOpen class="size-8 text-primary" />
+      </div>
+      <h2 class="text-2xl font-semibold tracking-tight">
+        Welcome to PRD Viewer
+      </h2>
+      <p class="mt-2 text-muted-foreground">
+        Add a repository to get started. The repository should contain PRD documents in a <code class="rounded bg-muted px-1.5 py-0.5 text-sm">docs/prd/</code> directory.
+      </p>
+
+      <form class="mt-6 space-y-4 text-left" @submit.prevent="handleAddRepo">
+        <div class="space-y-2">
+          <label for="repo-path" class="text-sm font-medium">
+            Repository Path
+          </label>
+          <div class="flex gap-2">
+            <Input
+              id="repo-path"
+              v-model="newRepoPath"
+              placeholder="/path/to/your/project"
+              :disabled="isAdding"
+              class="flex-1"
+            />
+            <Button
+              type="button"
+              variant="outline"
+              size="icon"
+              :disabled="isAdding"
+              @click="openBrowser"
+            >
+              <Folder class="size-4" />
+            </Button>
+          </div>
+          <p v-if="addError" class="text-sm text-destructive">
+            {{ addError }}
+          </p>
+        </div>
+
+        <!-- Directory Browser -->
+        <div v-if="showBrowser" class="space-y-2 rounded-md border p-3">
+          <div class="flex items-center gap-2 text-sm">
+            <button
+              type="button"
+              class="hover:text-foreground text-muted-foreground"
+              :disabled="browserPath === '/'"
+              @click="navigateUp"
+            >
+              ..
+            </button>
+            <span class="flex-1 truncate font-mono text-xs text-muted-foreground">
+              {{ browserPath }}
+            </span>
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              class="h-7 text-xs"
+              @click="selectDirectory(browserPath)"
+            >
+              Select
+            </Button>
+          </div>
+          <div class="max-h-[200px] overflow-y-auto">
+            <div v-if="browserLoading" class="py-2 text-center text-sm text-muted-foreground">
+              Loading...
+            </div>
+            <div v-else-if="!browserDirs.length" class="py-2 text-center text-sm text-muted-foreground">
+              No subdirectories
+            </div>
+            <button
+              v-for="dir in browserDirs"
+              v-else
+              :key="dir.path"
+              type="button"
+              class="flex w-full items-center gap-2 rounded px-2 py-1 text-sm hover:bg-accent"
+              @click="browseDirectory(dir.path)"
+            >
+              <Folder class="size-4 text-muted-foreground" />
+              <span class="truncate">{{ dir.name }}</span>
+            </button>
+          </div>
+        </div>
+
+        <Button type="submit" class="w-full" :disabled="isAdding">
+          <span v-if="isAdding">Adding...</span>
+          <span v-else>Add Repository</span>
+        </Button>
+      </form>
+    </div>
+
+    <!-- Select prompt: Repos exist but none selected -->
+    <div v-else-if="showSelectPrompt" class="mx-auto max-w-md text-center">
+      <div class="mx-auto mb-6 flex size-16 items-center justify-center rounded-full bg-primary/10">
+        <FolderOpen class="size-8 text-primary" />
+      </div>
+      <h2 class="text-2xl font-semibold tracking-tight">
+        Select a Repository
+      </h2>
+      <p class="mt-2 text-muted-foreground">
+        Choose a repository from the dropdown in the header to view its PRD documents.
+      </p>
+      <div class="mt-6 flex items-center justify-center gap-2 text-sm text-muted-foreground">
+        <ArrowRight class="size-4" />
+        <span>Use the repository selector above</span>
+      </div>
+    </div>
+
+    <!-- Welcome: Repo selected but no PRDs -->
+    <div v-else-if="showWelcome" class="mx-auto max-w-md text-center">
+      <div class="mx-auto mb-6 flex size-16 items-center justify-center rounded-full bg-muted">
+        <FileText class="size-8 text-muted-foreground" />
+      </div>
+      <h2 class="text-2xl font-semibold tracking-tight">
+        No PRDs Found
+      </h2>
+      <p class="mt-2 text-muted-foreground">
+        This repository doesn't have any PRD documents yet. Add markdown files to <code class="rounded bg-muted px-1.5 py-0.5 text-sm">docs/prd/</code> to get started.
+      </p>
+    </div>
+
+    <!-- PRD list: Repo selected with PRDs - show welcome with PRD count -->
+    <div v-else-if="showPrdList" class="mx-auto max-w-md text-center">
+      <div class="mx-auto mb-6 flex size-16 items-center justify-center rounded-full bg-primary/10">
+        <FileText class="size-8 text-primary" />
+      </div>
+      <h2 class="text-2xl font-semibold tracking-tight">
+        {{ currentRepo?.name }}
+      </h2>
+      <p class="mt-2 text-muted-foreground">
+        {{ prds?.length }} PRD{{ prds?.length === 1 ? '' : 's' }} available. Select one from the sidebar to view details.
+      </p>
+      <div class="mt-6 flex items-center justify-center gap-2 text-sm text-muted-foreground">
+        <ArrowRight class="size-4 rotate-180" />
+        <span>Choose a PRD from the sidebar</span>
+      </div>
+    </div>
+
+    <!-- Loading state -->
+    <div v-else class="mx-auto max-w-md text-center">
+      <div class="mx-auto mb-6 flex size-16 items-center justify-center">
+        <div class="size-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
+      </div>
+      <p class="text-muted-foreground">Loading...</p>
+    </div>
+  </div>
+</template>

package/app/types/git.ts

@@ -0,0 +1,81 @@
+/**
+ * Git commit information
+ */
+export interface GitCommit {
+  /** Full commit SHA */
+  sha: string
+  /** Short commit SHA (7 characters) */
+  shortSha: string
+  /** Commit message (first line) */
+  message: string
+  /** Author name */
+  author: string
+  /** Commit date as ISO string */
+  date: string
+  /** Number of files changed */
+  filesChanged: number
+  /** Total lines added */
+  additions: number
+  /** Total lines deleted */
+  deletions: number
+  /** Relative path to git repo for pseudo-monorepos (e.g., "code-hospitality-backend") */
+  repoPath?: string
+}
+
+/**
+ * File change status in a commit
+ */
+export type FileStatus = 'added' | 'modified' | 'deleted' | 'renamed'
+
+/**
+ * File diff summary within a commit
+ */
+export interface FileDiff {
+  /** Current file path */
+  path: string
+  /** Change status */
+  status: FileStatus
+  /** Original file path (for renames) */
+  oldPath?: string
+  /** Lines added in this file */
+  additions: number
+  /** Lines deleted in this file */
+  deletions: number
+  /** Whether this is a binary file */
+  binary?: boolean
+}
+
+/**
+ * Type of diff line
+ */
+export type DiffLineType = 'add' | 'remove' | 'context'
+
+/**
+ * Single line in a diff hunk
+ */
+export interface DiffLine {
+  /** Line type: addition, removal, or context */
+  type: DiffLineType
+  /** Line content (without +/- prefix) */
+  content: string
+  /** Line number in old file (for remove/context lines) */
+  oldNumber?: number
+  /** Line number in new file (for add/context lines) */
+  newNumber?: number
+}
+
+/**
+ * A hunk (section) of a diff
+ */
+export interface DiffHunk {
+  /** Starting line in old file */
+  oldStart: number
+  /** Number of lines from old file */
+  oldLines: number
+  /** Starting line in new file */
+  newStart: number
+  /** Number of lines in new file */
+  newLines: number
+  /** Lines in this hunk */
+  lines: DiffLine[]
+}

package/app/types/index.ts

@@ -0,0 +1,29 @@
+// Repository types
+export type { RepoConfig, AddRepoRequest, GitRepoInfo } from './repo'
+
+// PRD types
+export type { PrdListItem, PrdMetadata, PrdDocument } from './prd'
+
+// Task types
+export type {
+  TaskCategory,
+  TaskPriority,
+  TaskStatus,
+  Task,
+  TasksPrdInfo,
+  TasksFile,
+  ProgressPattern,
+  CommitRef,
+  TaskLog,
+  ProgressFile,
+} from './task'
+
+// Git types
+export type {
+  GitCommit,
+  FileStatus,
+  FileDiff,
+  DiffLineType,
+  DiffLine,
+  DiffHunk,
+} from './git'

package/app/types/prd.ts

@@ -0,0 +1,49 @@
+/**
+ * PRD list item returned when listing PRDs in a repository
+ */
+export interface PrdListItem {
+  /** URL-safe identifier (derived from filename) */
+  slug: string
+  /** PRD title extracted from markdown H1 */
+  name: string
+  /** Relative path to the .md file */
+  source: string
+  /** Whether tracked task/progress state exists for this PRD */
+  hasState: boolean
+  /** Total number of tasks if state exists */
+  taskCount?: number
+  /** Number of completed tasks if state exists */
+  completedCount?: number
+  /** File modification timestamp (ms since epoch) */
+  modifiedAt: number
+}
+
+/**
+ * PRD metadata extracted from document header
+ */
+export interface PrdMetadata {
+  /** Document author */
+  author?: string
+  /** Creation/update date */
+  date?: string
+  /** Document status (Draft, In Progress, Complete, etc.) */
+  status?: string
+  /** Shortcut story ID if linked */
+  shortcutStory?: string
+  /** Shortcut story URL if linked */
+  shortcutUrl?: string
+}
+
+/**
+ * Full PRD document with content and metadata
+ */
+export interface PrdDocument {
+  /** URL-safe identifier */
+  slug: string
+  /** PRD title */
+  name: string
+  /** Raw markdown content */
+  content: string
+  /** Extracted metadata */
+  metadata: PrdMetadata
+}

package/app/types/repo.ts

@@ -0,0 +1,37 @@
+/**
+ * Information about a discovered git repository within a pseudo-monorepo
+ */
+export interface GitRepoInfo {
+  /** Relative path from registered repo root (e.g., "code-hospitality-backend") */
+  relativePath: string
+  /** Absolute filesystem path to the git repo */
+  absolutePath: string
+  /** Display name (usually folder name) */
+  name: string
+}
+
+/**
+ * Repository configuration stored server-side
+ */
+export interface RepoConfig {
+  /** Unique identifier (UUID) */
+  id: string
+  /** Display name for the repository */
+  name: string
+  /** Absolute filesystem path to the repository */
+  path: string
+  /** ISO timestamp when the repo was added */
+  addedAt: string
+  /** Discovered git repositories for pseudo-monorepos (empty/undefined for standard repos) */
+  gitRepos?: GitRepoInfo[]
+}
+
+/**
+ * Request body for adding a new repository
+ */
+export interface AddRepoRequest {
+  /** Absolute filesystem path to the repository */
+  path: string
+  /** Optional display name (defaults to directory name) */
+  name?: string
+}

package/app/types/task.ts

@@ -0,0 +1,134 @@
+/**
+ * Task category
+ */
+export type TaskCategory = 'setup' | 'feature' | 'integration' | 'testing' | 'documentation'
+
+/**
+ * Task priority level
+ */
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low'
+
+/**
+ * Task status
+ */
+export type TaskStatus = 'pending' | 'in_progress' | 'completed'
+
+/**
+ * Individual task from tasks.json
+ */
+export interface Task {
+  /** Unique task identifier (e.g., "task-001") */
+  id: string
+  /** Task category */
+  category: TaskCategory
+  /** Short task title */
+  title: string
+  /** Detailed description of what needs to be done */
+  description: string
+  /** Specific implementation steps */
+  steps: string[]
+  /** Verification criteria for completion */
+  passes: string[]
+  /** IDs of tasks this task depends on */
+  dependencies: string[]
+  /** Task priority */
+  priority: TaskPriority
+  /** Current task status */
+  status: TaskStatus
+  /** ISO timestamp when task was started */
+  startedAt?: string
+  /** ISO timestamp when task was completed */
+  completedAt?: string
+}
+
+/**
+ * PRD metadata in tasks.json
+ */
+export interface TasksPrdInfo {
+  /** PRD name/title */
+  name: string
+  /** Path to source PRD markdown file */
+  source: string
+  /** Shortcut story ID if linked */
+  shortcutStory?: string
+  /** ISO timestamp when tasks were created */
+  createdAt: string
+}
+
+/**
+ * Full tasks.json structure
+ */
+export interface TasksFile {
+  /** PRD information */
+  prd: TasksPrdInfo
+  /** Array of tasks */
+  tasks: Task[]
+}
+
+/**
+ * Pattern discovered during implementation
+ */
+export interface ProgressPattern {
+  /** Pattern name */
+  name: string
+  /** Pattern description */
+  description: string
+}
+
+/**
+ * Commit reference with repository context for pseudo-monorepos
+ */
+export interface CommitRef {
+  /** Git commit SHA */
+  sha: string
+  /** Relative path to git repo from registered repo root (e.g., "code-hospitality-backend") */
+  repo: string
+}
+
+/**
+ * Log entry for a completed task
+ */
+export interface TaskLog {
+  /** Task ID */
+  taskId: string
+  /** Task status */
+  status: TaskStatus
+  /** ISO timestamp when task was started */
+  startedAt: string
+  /** ISO timestamp when task was completed */
+  completedAt?: string
+  /** Description of what was implemented */
+  implemented?: string
+  /** Files that were changed */
+  filesChanged?: string[]
+  /** Learnings or patterns discovered */
+  learnings?: string
+  /** Git commit SHAs associated with this task - supports both legacy strings and CommitRef objects */
+  commits?: (string | CommitRef)[]
+}
+
+/**
+ * Progress tracking file structure (progress.json)
+ */
+export interface ProgressFile {
+  /** PRD name */
+  prdName: string
+  /** Shortcut story ID if linked */
+  shortcutStory?: string
+  /** Total number of tasks */
+  totalTasks: number
+  /** Number of completed tasks */
+  completed: number
+  /** Number of in-progress tasks */
+  inProgress: number
+  /** Number of blocked tasks */
+  blocked: number
+  /** ISO timestamp when work started */
+  startedAt: string | null
+  /** ISO timestamp of last update */
+  lastUpdated: string
+  /** Discovered patterns */
+  patterns: ProgressPattern[]
+  /** Task completion logs */
+  taskLogs: TaskLog[]
+}

package/bin/prd

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const entryPath = resolve(packageRoot, 'dist', 'host', 'src', 'index.js')
+
+if (!existsSync(entryPath)) {
+  console.error('Steward host runtime is not built.')
+  console.error('Run `npm run build:host` in this package before invoking `prd`.')
+  process.exit(1)
+}
+
+const { main } = await import(pathToFileURL(entryPath).href)
+
+await main(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`Error: ${message}`)
+  process.exit(1)
+})

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://shadcn-vue.com/schema.json",
+  "style": "new-york",
+  "typescript": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/assets/css/main.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "composables": "@/composables"
+  },
+  "registries": {}
+}

package/dist/app/types/git.js

@@ -0,0 +1 @@
+export {};

package/dist/app/types/prd.js

@@ -0,0 +1 @@
+export {};

package/dist/app/types/repo.js

@@ -0,0 +1 @@
+export {};

package/dist/app/types/task.js

@@ -0,0 +1 @@
+export {};