popilot 0.3.0 → 0.5.0

package/scaffold/spec-site/src/composables/usePageContent.ts

@@ -0,0 +1,208 @@
+/**
+ * usePageContent — Load page content (rules, scenarios, specAreas, versions, meta)
+ *
+ * Stale-while-revalidate pattern:
+ * - localStorage cache for instant render + background API fetch
+ * - API failure gracefully falls back to cache
+ *
+ * In static mode, returns empty content (pages use local data files instead).
+ */
+
+import { ref, type Ref } from 'vue'
+import { apiGet, isStaticMode } from '@/api/client'
+import type { PageContentApiResponse } from '@/api/types'
+import type { Rule, Scenario, SpecArea, PageVersion, VersionChange } from '@/data/types'
+
+// ── Row → Domain mappers ──
+
+function rowToRule(row: PageContentApiResponse['rules'][number]): Rule {
+  return {
+    id: row.id,
+    category: row.category,
+    name: row.name,
+    condition: row.condition,
+    severity: row.severity,
+    homeMessage: row.home_message,
+    action: row.action,
+    dataSource: row.data_source,
+    implStatus: row.impl_status,
+    implNote: row.impl_note ?? undefined,
+    actionRoute: row.action_route ?? undefined,
+  }
+}
+
+// ── Cache helpers ──
+
+function cacheKey(pageId: string, sprint: string) {
+  return `spec_content_${pageId}_${sprint}`
+}
+
+interface CachedContent {
+  rules: Record<string, Rule[]>
+  scenarios: Scenario<any>[]
+  specAreas: SpecArea[]
+  version: PageVersion | null
+  wireframeMeta: { specTitle: string; routeTitle: string; defaultScenarioId: string } | null
+  ts: number
+}
+
+function loadCache(pageId: string, sprint: string): CachedContent | null {
+  try {
+    const raw = localStorage.getItem(cacheKey(pageId, sprint))
+    if (!raw) return null
+    return JSON.parse(raw) as CachedContent
+  } catch {
+    return null
+  }
+}
+
+function saveCache(pageId: string, sprint: string, content: CachedContent) {
+  try {
+    localStorage.setItem(cacheKey(pageId, sprint), JSON.stringify(content))
+  } catch {
+    // localStorage full — silently fail
+  }
+}
+
+// ── Public API ──
+
+export interface PageContent {
+  rules: Ref<Record<string, Rule[]>>
+  scenarios: Ref<Scenario<any>[]>
+  specAreas: Ref<SpecArea[]>
+  version: Ref<PageVersion | null>
+  wireframeMeta: Ref<{ specTitle: string; routeTitle: string; defaultScenarioId: string } | null>
+  loading: Ref<boolean>
+  error: Ref<string | null>
+  load: () => Promise<void>
+  getRuleGroup: (group: string) => Rule[]
+}
+
+export function usePageContent(pageId: string, sprint: string): PageContent {
+  const rules = ref<Record<string, Rule[]>>({})
+  const scenarios = ref<Scenario<any>[]>([])
+  const specAreas = ref<SpecArea[]>([])
+  const version = ref<PageVersion | null>(null)
+  const wireframeMeta = ref<{ specTitle: string; routeTitle: string; defaultScenarioId: string } | null>(null)
+  const loading = ref(true)
+  const error = ref<string | null>(null)
+
+  function applyContent(content: CachedContent) {
+    rules.value = content.rules
+    scenarios.value = content.scenarios
+    specAreas.value = content.specAreas
+    version.value = content.version
+    wireframeMeta.value = content.wireframeMeta
+  }
+
+  function transformResponse(data: PageContentApiResponse): CachedContent {
+    // Transform rules: group by rule_group
+    const rulesByGroup: Record<string, Rule[]> = {}
+    for (const row of data.rules) {
+      const group = row.rule_group
+      if (!rulesByGroup[group]) rulesByGroup[group] = []
+      rulesByGroup[group].push(rowToRule(row))
+    }
+
+    // Transform scenarios
+    const scenarioList: Scenario<any>[] = data.scenarios.map(row => ({
+      id: row.scenario_id,
+      label: row.label,
+      data: JSON.parse(row.data_json),
+    }))
+
+    // Transform spec areas
+    const areaList: SpecArea[] = data.areas.map(row => ({
+      id: row.area_id,
+      label: row.label,
+      shortLabel: row.short_label,
+      ruleCount: row.rule_count,
+    }))
+
+    // Transform version
+    const vRow = data.versions[0]
+    const pageVersion: PageVersion | null = vRow
+      ? {
+        page: vRow.page_id,
+        version: vRow.version,
+        lastUpdated: vRow.last_updated,
+        sprint: vRow.sprint,
+        status: vRow.status as PageVersion['status'],
+        changelog: JSON.parse(vRow.changelog) as VersionChange[],
+      }
+      : null
+
+    // Transform wireframe meta
+    const mRow = data.meta[0]
+    const meta = mRow
+      ? {
+        specTitle: mRow.spec_title,
+        routeTitle: mRow.route_title,
+        defaultScenarioId: mRow.default_scenario_id,
+      }
+      : null
+
+    return {
+      rules: rulesByGroup,
+      scenarios: scenarioList,
+      specAreas: areaList,
+      version: pageVersion,
+      wireframeMeta: meta,
+      ts: Date.now(),
+    }
+  }
+
+  async function load() {
+    if (isStaticMode()) {
+      loading.value = false
+      return
+    }
+
+    loading.value = true
+    error.value = null
+
+    // 1. Try cache first (stale-while-revalidate)
+    const cached = loadCache(pageId, sprint)
+    if (cached) {
+      applyContent(cached)
+      loading.value = false
+    }
+
+    // 2. Fetch from API (background if cache existed)
+    try {
+      const { data, error: apiError } = await apiGet<PageContentApiResponse>(
+        `/api/v2/page-content/${encodeURIComponent(pageId)}/${encodeURIComponent(sprint)}`,
+      )
+      if (apiError || !data) throw new Error(apiError ?? 'Unknown error')
+
+      const fresh = transformResponse(data)
+      applyContent(fresh)
+      saveCache(pageId, sprint, fresh)
+      error.value = null
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Unknown error'
+      if (!cached) {
+        error.value = msg
+      }
+      console.warn(`[usePageContent] API fetch failed for ${pageId}/${sprint}: ${msg}`)
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function getRuleGroup(group: string): Rule[] {
+    return rules.value[group] ?? []
+  }
+
+  return {
+    rules,
+    scenarios,
+    specAreas,
+    version,
+    wireframeMeta,
+    loading,
+    error,
+    load,
+    getRuleGroup,
+  }
+}

package/scaffold/spec-site/src/composables/usePmStore.ts

@@ -0,0 +1,224 @@
+/**
+ * PM Store — API-backed epics, stories & tasks
+ *
+ * Singleton pattern: refs are module-level, shared across all consumers.
+ * In static mode, all data is empty and CRUD operations are disabled.
+ */
+
+import { ref } from 'vue'
+import { apiGet, apiPost, apiPatch, apiDelete, isStaticMode } from '@/api/client'
+import {
+  type PmEpic, type PmStory, type PmTask,
+  type StoryStatus, type TaskStatus, type Priority, type EpicStatus,
+  mapEpic, mapStory, mapTask,
+} from './pmTypes'
+import type { PmEpicRow, PmStoryRow, PmTaskRow } from '@/api/types'
+
+export type { StoryStatus, TaskStatus, Priority, EpicStatus, PmEpic, PmStory, PmTask } from './pmTypes'
+export {
+  STORY_STATUSES, TASK_STATUSES, PRIORITIES, AREAS, EPIC_STATUSES,
+  STORY_STATUS_LABELS, TASK_STATUS_LABELS, PRIORITY_LABELS, EPIC_STATUS_LABELS,
+} from './pmTypes'
+
+// ── Singleton state ──
+
+export const pmEpics = ref<PmEpic[]>([])
+export const stories = ref<PmStory[]>([])
+export const tasks = ref<PmTask[]>([])
+export const pmLoaded = ref(false)
+
+// ── Load ──
+
+export async function loadEpics(): Promise<void> {
+  if (isStaticMode()) return
+  const { data, error } = await apiGet<{ epics: PmEpicRow[] }>('/api/v2/pm/epics')
+  if (!error && data) {
+    pmEpics.value = data.epics.map(mapEpic)
+  }
+}
+
+export async function loadPmData(sprint?: string): Promise<void> {
+  if (isStaticMode()) { pmLoaded.value = true; return }
+  const params: Record<string, string> = {}
+  if (sprint) params.sprint = sprint
+
+  const { data, error } = await apiGet<{ stories: PmStoryRow[]; tasks: PmTaskRow[] }>(
+    '/api/v2/pm/data', params,
+  )
+
+  if (!error && data) {
+    stories.value = data.stories.map(mapStory)
+    tasks.value = data.tasks.map(mapTask)
+  }
+
+  pmLoaded.value = true
+}
+
+// ── Epic CRUD ──
+
+export async function addEpic(data: {
+  title: string
+  description?: string | null
+  status?: EpicStatus
+  owner?: string | null
+}): Promise<{ id?: number; error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { data: resp, error } = await apiPost<{ id?: number }>('/api/v2/pm/epics', {
+    title: data.title,
+    description: data.description ?? null,
+    status: data.status ?? 'active',
+    owner: data.owner ?? null,
+  })
+  if (error) return { error }
+  await loadEpics()
+  return { id: resp?.id }
+}
+
+export async function updateEpic(id: number, data: {
+  title?: string
+  description?: string | null
+  status?: EpicStatus
+  owner?: string | null
+}): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiPatch(`/api/v2/pm/epics/${id}`, data as Record<string, unknown>)
+  if (error) return { error }
+  await loadEpics()
+  return {}
+}
+
+export async function deleteEpic(id: number): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiDelete(`/api/v2/pm/epics/${id}`)
+  if (error) return { error }
+  await loadEpics()
+  return {}
+}
+
+// ── Story CRUD ──
+
+export async function addStory(data: {
+  epicId: number | null
+  sprint: string
+  title: string
+  description?: string | null
+  acceptanceCriteria?: string | null
+  assignee?: string | null
+  status?: StoryStatus
+  priority?: Priority
+  area?: string
+  storyPoints?: number | null
+}): Promise<{ id?: number; error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const maxOrder = stories.value
+    .filter(s => s.sprint === data.sprint)
+    .reduce((max, s) => Math.max(max, s.sortOrder), -1)
+
+  const { data: resp, error } = await apiPost<{ id?: number }>('/api/v2/pm/stories', {
+    epicId: data.epicId,
+    sprint: data.sprint,
+    title: data.title,
+    description: data.description ?? null,
+    acceptanceCriteria: data.acceptanceCriteria ?? null,
+    assignee: data.assignee ?? null,
+    status: data.status ?? 'draft',
+    priority: data.priority ?? 'medium',
+    area: data.area ?? 'FE',
+    storyPoints: data.storyPoints ?? null,
+    sortOrder: maxOrder + 1,
+  })
+  if (error) return { error }
+  await loadPmData(data.sprint)
+  return { id: resp?.id }
+}
+
+export async function updateStory(id: number, data: {
+  title?: string
+  description?: string | null
+  acceptanceCriteria?: string | null
+  assignee?: string | null
+  status?: StoryStatus
+  priority?: Priority
+  area?: string
+  storyPoints?: number | null
+  epicId?: number | null
+  sprint?: string
+}): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiPatch(`/api/v2/pm/stories/${id}`, data as Record<string, unknown>)
+  if (error) return { error }
+  await loadPmData()
+  return {}
+}
+
+export async function deleteStory(id: number): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiDelete(`/api/v2/pm/stories/${id}`)
+  if (error) return { error }
+  await loadPmData()
+  return {}
+}
+
+// ── Task CRUD ──
+
+export async function addTask(data: {
+  storyId: number
+  title: string
+  assignee?: string | null
+  description?: string | null
+}): Promise<{ id?: number; error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const maxOrder = tasks.value
+    .filter(t => t.storyId === data.storyId)
+    .reduce((max, t) => Math.max(max, t.sortOrder), -1)
+
+  const { data: resp, error } = await apiPost<{ id?: number }>('/api/v2/pm/tasks', {
+    storyId: data.storyId,
+    title: data.title,
+    assignee: data.assignee ?? null,
+    description: data.description ?? null,
+    sortOrder: maxOrder + 1,
+  })
+  if (error) return { error }
+  await loadPmData()
+  return { id: resp?.id }
+}
+
+export async function updateTask(id: number, data: {
+  title?: string
+  assignee?: string | null
+  status?: TaskStatus
+  description?: string | null
+}): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiPatch(`/api/v2/pm/tasks/${id}`, data as Record<string, unknown>)
+  if (error) return { error }
+  await loadPmData()
+  return {}
+}
+
+export async function deleteTask(id: number): Promise<{ error?: string }> {
+  if (isStaticMode()) return { error: 'CRUD not available in static mode' }
+  const { error } = await apiDelete(`/api/v2/pm/tasks/${id}`)
+  if (error) return { error }
+  await loadPmData()
+  return {}
+}
+
+// ── Helpers ──
+
+export function getStoriesForEpic(epicId: number): PmStory[] {
+  return stories.value.filter(s => s.epicId === epicId)
+}
+
+export function getStoriesForSprint(sprint: string): PmStory[] {
+  return stories.value.filter(s => s.sprint === sprint)
+}
+
+export function getEpicById(id: number): PmEpic | undefined {
+  return pmEpics.value.find(e => e.id === id)
+}
+
+export function getTasksForStory(storyId: number): PmTask[] {
+  return tasks.value.filter(t => t.storyId === storyId)
+}