@thxgg/steward 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+# Optional: absolute path to the global PRD SQLite database file.
+# If unset, PRD Viewer uses ${XDG_DATA_HOME:-~/.local/share}/prd/state.db.
+PRD_STATE_DB_PATH=
+
+# Optional: base directory for global PRD state.
+# When set, database path resolves to <PRD_STATE_HOME>/state.db.
+PRD_STATE_HOME=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thxgg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# Steward
+
+Steward is a local-first Nuxt app for browsing Product Requirements Documents and tracking implementation state in a global SQLite database.
+
+It is published as `@thxgg/steward` and provides the `prd` CLI command.
+
+This project is intended to be downloaded and run locally on your machine. It is not designed for public internet deployment.
+
+## What It Does
+
+- Scans repositories for `docs/prd/*.md` files and displays them in a focused UI.
+- Reads task state (`tasks.json` and `progress.json`) from a global SQLite database.
+- Supports legacy `.claude/state/*` migration into the global database.
+- Resolves commit references for tasks, including pseudo-monorepo sub-repo contexts.
+
+## Local-First Security Model
+
+Steward exposes local filesystem and git metadata for convenience. Because of that:
+
+- Run it only on trusted local machines.
+- Do not expose it directly to the public internet.
+- Treat it as a developer workstation tool, not a hosted multi-user service.
+
+## Requirements
+
+- Node.js 22+
+- npm (or pnpm)
+- Git
+- Linux/macOS (or compatible environment)
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+With pnpm:
+
+```bash
+pnpm install
+pnpm run dev
+```
+
+Open `http://localhost:3000`, then add a local repository path that contains a `docs/prd/` directory.
+
+## Install CLI
+
+```bash
+npm install -g @thxgg/steward
+prd ui
+```
+
+With pnpm:
+
+```bash
+pnpm add -g @thxgg/steward
+prd ui
+```
+
+Without global install:
+
+```bash
+npx -y @thxgg/steward ui
+```
+
+You can also run the app through the project CLI:
+
+```bash
+npm run ui
+```
+
+## Scripts
+
+- `npm run dev` - Start local dev server
+- `npm run typecheck` - Run Nuxt type checking
+- `npm run build` - Build production bundle
+- `npm run preview` - Preview the production build locally
+- `npm run ui` - Launch `prd ui` (dev mode)
+- `npm run mcp` - Start MCP server over stdio
+
+## CLI
+
+This package ships a `prd` command.
+
+- npm package: `@thxgg/steward`
+
+- `prd ui` - Launch the web app in dev mode (default)
+- `prd ui --preview` - Launch the production preview server
+- `prd ui --port 3100 --host 127.0.0.1` - Pass Nuxt host/port options
+- `prd mcp` - Run the codemode MCP server over stdio
+
+For local shell usage while developing this repo:
+
+```bash
+npm link
+prd ui
+```
+
+## MCP Usage
+
+The MCP server exposes one codemode tool: `execute`.
+
+The codemode runtime has these APIs in scope:
+
+- `repos` - list/add/remove/refresh repository registrations
+- `prds` - list/get PRD documents and state-backed task/progress data
+- `git` - commit metadata, diffs, and file content lookups
+- `state` - direct PRD state reads/writes in SQLite
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "prd": {
+      "command": "prd",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+For codemode API details and examples, see `docs/MCP.md`.
+
+## Global PRD State Storage
+
+PRD state is system-global and stored in SQLite:
+
+- Default: `${XDG_DATA_HOME:-~/.local/share}/prd/state.db`
+- Override full path: `PRD_STATE_DB_PATH`
+- Override base dir: `PRD_STATE_HOME` (resolved to `<PRD_STATE_HOME>/state.db`)
+
+This allows multiple local repos to share one PRD state store.
+
+## Environment Variables
+
+Copy `.env.example` to `.env` if you want to override defaults.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `PRD_STATE_DB_PATH` | No | Absolute path to SQLite database file |
+| `PRD_STATE_HOME` | No | Directory used for database home (`state.db` inside it) |
+| `XDG_DATA_HOME` | No | Used for default global state location |
+
+## OpenCode Bundle Included
+
+This repository includes a curated OpenCode bundle under `opencode/`:
+
+- Commands: `prd`, `prd-task`, `complete-next-task`, `commit`
+- Skills: `prd`, `prd-task`, `complete-next-task`, `commit`
+- Script: `prd-db.mjs`
+
+`frontend-design` is intentionally not included.
+
+To install into a local OpenCode config:
+
+```bash
+mkdir -p ~/.config/opencode
+cp -R opencode/commands ~/.config/opencode/
+cp -R opencode/skills ~/.config/opencode/
+cp -R opencode/scripts ~/.config/opencode/
+```
+
+## CI
+
+GitHub Actions runs:
+
+- Typecheck + build validation
+- Secret scanning with gitleaks
+
+## Roadmap
+
+- Continue hardening local-only workflows
+- Expand codemode APIs and automation patterns

package/app/app.vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import { Toaster } from 'vue-sonner'
+
+const { resolvedTheme } = useThemeMode()
+</script>
+
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+  <ClientOnly>
+    <Toaster position="bottom-right" :theme="resolvedTheme" rich-colors />
+  </ClientOnly>
+</template>

package/app/assets/css/main.css

@@ -0,0 +1,129 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+/* Hide scrollbar utility */
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}

package/app/components/CommandPalette.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import { FileText, Monitor, Moon, Sun, LayoutGrid, Folder, Check, Keyboard, RefreshCw } from 'lucide-vue-next'
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator
+} from '~/components/ui/command'
+
+const open = defineModel<boolean>('open', { default: false })
+const filter = defineModel<string>('filter', { default: '' })
+
+const emit = defineEmits<{
+  openShortcutsHelp: []
+}>()
+
+const router = useRouter()
+const { themeMode, cycleThemeMode } = useThemeMode()
+const { prds } = usePrd()
+const { repos, currentRepoId, selectRepo, refreshGitRepos } = useRepos()
+const { showSuccess, showError } = useToast()
+
+// Get current tab from localStorage
+const currentTab = ref<'document' | 'board'>('document')
+
+if (import.meta.client) {
+  const saved = localStorage.getItem('prd-viewer-tab')
+  if (saved === 'document' || saved === 'board') {
+    currentTab.value = saved
+  }
+}
+
+function navigateToPrd(slug: string) {
+  if (!currentRepoId.value) return
+  router.push(`/${currentRepoId.value}/${slug}`)
+  open.value = false
+}
+
+function switchRepo(repoId: string) {
+  selectRepo(repoId)
+  router.push('/')
+  open.value = false
+}
+
+function toggleTheme() {
+  cycleThemeMode()
+  open.value = false
+}
+
+function toggleTab() {
+  const newTab = currentTab.value === 'document' ? 'board' : 'document'
+  currentTab.value = newTab
+  if (import.meta.client) {
+    localStorage.setItem('prd-viewer-tab', newTab)
+    // Dispatch a storage event so the page can react
+    window.dispatchEvent(new StorageEvent('storage', {
+      key: 'prd-viewer-tab',
+      newValue: newTab
+    }))
+  }
+  open.value = false
+}
+
+function openShortcutsHelp() {
+  open.value = false
+  emit('openShortcutsHelp')
+}
+
+const isRefreshingGitRepos = ref(false)
+
+async function handleRefreshGitRepos() {
+  if (!currentRepoId.value || isRefreshingGitRepos.value) return
+
+  isRefreshingGitRepos.value = true
+  open.value = false
+
+  try {
+    const result = await refreshGitRepos(currentRepoId.value)
+    showSuccess(`Discovered ${result.discovered} git repositories`)
+  } catch {
+    showError('Failed to refresh git repos')
+  } finally {
+    isRefreshingGitRepos.value = false
+  }
+}
+
+// Clear the filter when dialog closes
+watch(open, (isOpen) => {
+  if (!isOpen) {
+    filter.value = ''
+  }
+})
+
+// Detect platform for shortcut hints
+const isMac = computed(() => {
+  if (!import.meta.client) return true
+  return navigator.platform.toUpperCase().indexOf('MAC') >= 0
+})
+const modKey = computed(() => isMac.value ? '⌘' : 'Ctrl')
+</script>
+
+<template>
+  <CommandDialog v-model:open="open" :default-search="filter">
+    <CommandInput placeholder="Type a command or search..." />
+    <CommandList>
+      <CommandEmpty>No results found.</CommandEmpty>
+
+      <CommandGroup v-if="prds?.length" heading="Documents">
+        <CommandItem
+          v-for="prd in prds"
+          :key="prd.slug"
+          :value="`PRD: ${prd.name}`"
+          @select="navigateToPrd(prd.slug)"
+        >
+          <FileText class="size-4" />
+          <span>{{ prd.name }}</span>
+        </CommandItem>
+      </CommandGroup>
+
+      <CommandSeparator v-if="prds?.length && repos?.length" />
+
+      <CommandGroup v-if="repos?.length" heading="Repositories">
+        <CommandItem
+          v-for="repo in repos"
+          :key="repo.id"
+          :value="`repo-${repo.id} ${repo.name}`"
+          @select="switchRepo(repo.id)"
+        >
+          <Folder class="size-4" />
+          <span class="flex-1">{{ repo.name }}</span>
+          <Check v-if="repo.id === currentRepoId" class="size-4 text-primary" />
+        </CommandItem>
+      </CommandGroup>
+
+      <CommandSeparator v-if="repos?.length" />
+
+      <CommandGroup heading="Actions">
+        <CommandItem value="cycle-theme light dark system" @select="toggleTheme">
+          <Monitor v-if="themeMode === 'system'" class="size-4" />
+          <Sun v-else-if="themeMode === 'light'" class="size-4" />
+          <Moon v-else class="size-4" />
+          <span class="flex-1">Cycle theme mode ({{ themeMode }})</span>
+          <div class="ml-auto flex items-center gap-1">
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">{{ modKey }}</kbd>
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">.</kbd>
+          </div>
+        </CommandItem>
+        <CommandItem
+          :value="`switch-tab ${currentTab === 'document' ? 'task board' : 'document'}`"
+          @select="toggleTab"
+        >
+          <LayoutGrid class="size-4" />
+          <span class="flex-1">Switch to {{ currentTab === 'document' ? 'Task Board' : 'Document' }}</span>
+          <div class="ml-auto flex items-center gap-1">
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">{{ modKey }}</kbd>
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">\</kbd>
+          </div>
+        </CommandItem>
+        <CommandItem value="keyboard shortcuts help" @select="openShortcutsHelp">
+          <Keyboard class="size-4" />
+          <span class="flex-1">Keyboard shortcuts</span>
+          <div class="ml-auto flex items-center gap-1">
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">{{ modKey }}</kbd>
+            <kbd class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-[10px] text-muted-foreground">/</kbd>
+          </div>
+        </CommandItem>
+        <CommandItem
+          v-if="currentRepoId"
+          value="refresh git repos rescan discover"
+          :disabled="isRefreshingGitRepos"
+          @select="handleRefreshGitRepos"
+        >
+          <RefreshCw class="size-4" :class="{ 'animate-spin': isRefreshingGitRepos }" />
+          <span class="flex-1">Refresh git repos</span>
+        </CommandItem>
+      </CommandGroup>
+    </CommandList>
+  </CommandDialog>
+</template>

package/app/components/ShortcutsHelp.vue

@@ -0,0 +1,85 @@
+<script setup lang="ts">
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle
+} from '~/components/ui/dialog'
+
+const open = defineModel<boolean>('open', { default: false })
+
+// Detect if user is on Mac
+const isMac = computed(() => {
+  if (!import.meta.client) return true // Default to Mac for SSR
+  return navigator.platform.toUpperCase().indexOf('MAC') >= 0
+})
+
+// Modifier key display
+const modKey = computed(() => isMac.value ? '⌘' : 'Ctrl')
+
+// Shortcut groups
+const shortcutGroups = computed(() => [
+  {
+    name: 'Navigation',
+    shortcuts: [
+      { keys: [modKey.value, 'K'], description: 'Open command palette' },
+      { keys: [modKey.value, 'J'], description: 'Quick jump to document' }
+    ]
+  },
+  {
+    name: 'Actions',
+    shortcuts: [
+      { keys: [modKey.value, '.'], description: 'Cycle theme mode (light/dark/system)' },
+      { keys: [modKey.value, '\\'], description: 'Switch between Document and Task Board' },
+      { keys: [modKey.value, ','], description: 'Add repository' }
+    ]
+  },
+  {
+    name: 'Help',
+    shortcuts: [
+      { keys: [modKey.value, '/'], description: 'Show this help' },
+      { keys: ['Esc'], description: 'Close dialog or palette' }
+    ]
+  }
+])
+</script>
+
+<template>
+  <Dialog v-model:open="open">
+    <DialogContent class="max-w-md">
+      <DialogHeader>
+        <DialogTitle>Keyboard Shortcuts</DialogTitle>
+        <DialogDescription>
+          Quick reference for available keyboard shortcuts.
+        </DialogDescription>
+      </DialogHeader>
+
+      <div class="space-y-6">
+        <div v-for="group in shortcutGroups" :key="group.name">
+          <h3 class="mb-3 text-sm font-medium text-muted-foreground">
+            {{ group.name }}
+          </h3>
+          <div class="space-y-2">
+            <div
+              v-for="shortcut in group.shortcuts"
+              :key="shortcut.description"
+              class="flex items-center justify-between"
+            >
+              <span class="text-sm">{{ shortcut.description }}</span>
+              <div class="flex items-center gap-1">
+                <kbd
+                  v-for="(key, index) in shortcut.keys"
+                  :key="index"
+                  class="inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-mono text-xs font-medium text-muted-foreground"
+                >
+                  {{ key }}
+                </kbd>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </DialogContent>
+  </Dialog>
+</template>