@kynetic-ai/spec 0.9.1 → 0.11.0

package/dist/daemon/routes/plans.ts

@@ -0,0 +1,147 @@
+/**
+ * Plans API Routes
+ *
+ * REST endpoints for plan operations:
+ * - GET /api/plans - list plans with status filter and task progress
+ * - GET /api/plans/:ref - get single plan with content
+ *
+ * AC Coverage:
+ * - @ui-plans-view ac-1: Plan list with title, status, dates, linked counts, progress
+ * - @ui-plans-view ac-2: Plan detail with content for expand/detail view
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadPlans,
+  loadAllTasks,
+  findPlanByRef,
+  type LoadedPlan,
+} from '../../parser/index.js';
+import type { PlanSummary, PlanDetail } from '@kynetic-ai/shared';
+
+interface PlansRouteOptions {}
+
+/**
+ * Build a task status lookup map from loaded tasks.
+ */
+function buildTaskStatusMap(tasks: Array<{ _ulid: string; slugs: string[]; status: string }>) {
+  const tasksByRef = new Map<string, { status: string }>();
+  for (const task of tasks) {
+    tasksByRef.set(task._ulid, { status: task.status });
+    for (const slug of task.slugs) {
+      tasksByRef.set(slug, { status: task.status });
+    }
+  }
+  return tasksByRef;
+}
+
+/**
+ * Compute task progress for a plan's derived tasks.
+ */
+function computeTaskProgress(
+  derivedTasks: string[],
+  tasksByRef: Map<string, { status: string }>
+) {
+  const progress = { total: 0, completed: 0, in_progress: 0, pending: 0, blocked: 0 };
+  for (const ref of derivedTasks) {
+    const cleanRef = ref.startsWith('@') ? ref.slice(1) : ref;
+    const task = tasksByRef.get(cleanRef);
+    if (task) {
+      progress.total++;
+      if (task.status === 'completed') progress.completed++;
+      else if (task.status === 'in_progress' || task.status === 'pending_review' || task.status === 'needs_work') progress.in_progress++;
+      else if (task.status === 'blocked') progress.blocked++;
+      else progress.pending++;
+    }
+  }
+  return progress;
+}
+
+/**
+ * Map a loaded plan to a PlanSummary.
+ */
+function toPlanSummary(
+  plan: LoadedPlan,
+  tasksByRef: Map<string, { status: string }>
+): PlanSummary {
+  return {
+    _ulid: plan._ulid,
+    slugs: plan.slugs,
+    title: plan.title,
+    status: plan.status,
+    created_at: plan.created_at,
+    approved_at: plan.approved_at ?? undefined,
+    completed_at: plan.completed_at ?? undefined,
+    derived_specs: plan.derived_specs,
+    derived_tasks: plan.derived_tasks,
+    spec_count: plan.derived_specs.length,
+    task_count: plan.derived_tasks.length,
+    task_progress: computeTaskProgress(plan.derived_tasks, tasksByRef),
+  };
+}
+
+export function createPlansRoutes(options: PlansRouteOptions = {}) {
+  return new Elysia({ prefix: '/api/plans' })
+    // AC: @ui-plans-view ac-1 - List plans with progress
+    .get(
+      '/',
+      async ({ query, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const plans = await loadPlans(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const tasksByRef = buildTaskStatusMap(tasks);
+
+        // Apply status filter
+        let filtered: LoadedPlan[] = plans;
+        if (query.status) {
+          const statusFilters = Array.isArray(query.status) ? query.status : [query.status];
+          filtered = filtered.filter((plan) => statusFilters.includes(plan.status));
+        }
+
+        // Sort by created_at descending (newest first)
+        const sorted = [...filtered].sort(
+          (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+        );
+
+        // AC: @ui-plans-view ac-1 - Compute progress for each plan
+        const items: PlanSummary[] = sorted.map((plan) => toPlanSummary(plan, tasksByRef));
+
+        return {
+          items,
+          total: items.length,
+        };
+      },
+      {
+        query: t.Object({
+          status: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+        }),
+      }
+    )
+    // AC: @ui-plans-view ac-2 - Get single plan with content (lazy-loaded by UI on expand)
+    .get(
+      '/:ref',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const plan = await findPlanByRef(ctx, params.ref);
+
+        if (!plan) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Plan reference "${params.ref}" not found`,
+            suggestion: 'Use kspec plan list to find valid plan references',
+          });
+        }
+
+        const tasks = await loadAllTasks(ctx);
+        const tasksByRef = buildTaskStatusMap(tasks);
+
+        const detail: PlanDetail = {
+          ...toPlanSummary(plan, tasksByRef),
+          content: plan.content,
+        };
+
+        return detail;
+      }
+    );
+}

package/dist/daemon/routes/sessions.ts

@@ -0,0 +1,180 @@
+/**
+ * Session API Routes
+ *
+ * REST endpoints for session data:
+ * - GET /api/sessions - list sessions with summaries
+ * - GET /api/sessions/:id - get session metadata and detail
+ * - GET /api/sessions/:id/events - get session events from events.jsonl
+ *
+ * AC Coverage:
+ * - @ui-session-stream ac-1: Session events as structured blocks
+ * - @ui-session-stream ac-4: Session metadata, spec context, budget for context panel
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  getSession,
+  listSessions,
+  readEvents,
+  deduplicatePhasedToolCalls,
+  getSessionLogSummary,
+  getAllSessionLogSummaries,
+  resolveSessionId,
+  getBudget,
+} from '../../sessions/store.js';
+import {
+  initContext,
+  loadAllTasks,
+  loadAllItems,
+  ReferenceIndex,
+} from '../../parser/index.js';
+
+export function createSessionRoutes() {
+  return new Elysia({ prefix: '/api/sessions' })
+
+    // List all sessions with summaries
+    .get('/', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const summaries = await getAllSessionLogSummaries(ctx.specDir);
+
+      // Sort by started_at descending (most recent first)
+      summaries.sort((a, b) =>
+        new Date(b.started_at).getTime() - new Date(a.started_at).getTime()
+      );
+
+      return {
+        items: summaries,
+        total: summaries.length,
+      };
+    })
+
+    // Get single session metadata
+    // AC: @ui-session-stream ac-4 — Includes spec context, budget, and task info
+    .get('/:id', async ({ params, error: errorResponse, projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+
+      // Resolve session ID (supports prefix matching)
+      const resolution = await resolveSessionId(ctx.specDir, params.id);
+      if (!resolution.ok) {
+        if (resolution.error === 'ambiguous') {
+          return errorResponse(400, {
+            error: 'ambiguous_id',
+            message: `Ambiguous session ID: ${params.id} matches ${resolution.matches.length} sessions`,
+            suggestion: 'Provide a longer prefix to uniquely identify the session',
+          });
+        }
+        return errorResponse(404, {
+          error: 'not_found',
+          message: `Session not found: ${params.id}`,
+          suggestion: 'Use GET /api/sessions to list available sessions',
+        });
+      }
+
+      const detail = await getSessionLogSummary(ctx.specDir, resolution.id);
+      if (!detail) {
+        return errorResponse(404, {
+          error: 'not_found',
+          message: `Session not found: ${params.id}`,
+          suggestion: 'Use GET /api/sessions to list available sessions',
+        });
+      }
+
+      const metadata = await getSession(ctx.specDir, resolution.id);
+
+      // AC: @ui-session-stream ac-4 — Resolve spec context from task's spec_ref
+      let spec_context: {
+        spec_ref: string;
+        title: string;
+        acceptance_criteria: Array<{ id: string; description: string }>;
+      } | null = null;
+
+      if (metadata?.task_id) {
+        try {
+          const tasks = await loadAllTasks(ctx);
+          const items = await loadAllItems(ctx);
+          const index = new ReferenceIndex(tasks, items);
+          const taskResult = index.resolve(metadata.task_id);
+          if (taskResult.ok) {
+            const task = taskResult.item as { spec_ref?: string };
+            if (task.spec_ref) {
+              const specResult = index.resolve(task.spec_ref);
+              if (specResult.ok) {
+                const specItem = specResult.item as {
+                  title: string;
+                  acceptance_criteria?: Array<{ description?: string; given?: string }>;
+                };
+                spec_context = {
+                  spec_ref: task.spec_ref,
+                  title: specItem.title,
+                  acceptance_criteria: (specItem.acceptance_criteria ?? []).map((ac, i) => ({
+                    id: `ac-${i + 1}`,
+                    description: ac.description ?? ac.given ?? '',
+                  })),
+                };
+              }
+            }
+          }
+        } catch {
+          // Non-critical — spec context is optional
+        }
+      }
+
+      // AC: @ui-session-stream ac-4 — Include budget info
+      let budget: { max_per_cycle: number; started_this_cycle: number } | null = null;
+      try {
+        budget = await getBudget(ctx.specDir, resolution.id);
+      } catch {
+        // No budget configured — that's fine
+      }
+
+      return {
+        ...detail,
+        task_id: metadata?.task_id,
+        agent_id: metadata?.agent_id,
+        trigger: metadata?.trigger ?? 'legacy',
+        spec_context,
+        budget,
+      };
+    })
+
+    // Get session events
+    .get('/:id/events', async ({ params, query, error: errorResponse, projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+
+      const resolution = await resolveSessionId(ctx.specDir, params.id);
+      if (!resolution.ok) {
+        if (resolution.error === 'ambiguous') {
+          return errorResponse(400, {
+            error: 'ambiguous_id',
+            message: `Ambiguous session ID: ${params.id} matches ${resolution.matches.length} sessions`,
+            suggestion: 'Provide a longer prefix to uniquely identify the session',
+          });
+        }
+        return errorResponse(404, {
+          error: 'not_found',
+          message: `Session not found: ${params.id}`,
+          suggestion: 'Use GET /api/sessions to list available sessions',
+        });
+      }
+
+      let events = await readEvents(ctx.specDir, resolution.id);
+
+      // Deduplicate phased tool calls
+      events = deduplicatePhasedToolCalls(events);
+
+      // Filter by since_seq if provided (for incremental loading)
+      const sinceSeq = query.since_seq !== undefined ? parseInt(query.since_seq, 10) : undefined;
+      if (sinceSeq !== undefined && !isNaN(sinceSeq)) {
+        events = events.filter(e => e.seq > sinceSeq);
+      }
+
+      return {
+        events,
+        total: events.length,
+      };
+    }, {
+      query: t.Object({
+        since_seq: t.Optional(t.String()),
+      }),
+    });
+}

package/dist/daemon/routes/tasks.ts

@@ -14,6 +14,9 @@
  * - ac-5: GET /api/tasks/:ref resolves via ReferenceIndex
  * - ac-6: POST /api/tasks/:ref/start transitions state
  * - ac-7: POST /api/tasks/:ref/note appends note
+ * - @ui-task-board ac-6: POST /api/tasks/:ref/submit transitions to pending_review
+ * - @ui-task-board ac-6: POST /api/tasks/:ref/complete transitions to completed
+ * - @ui-task-board ac-6: POST /api/tasks/:ref/block transitions to blocked
  */
 
 import { Elysia, t } from 'elysia';
@@ -21,6 +24,7 @@ import {
   initContext,
   loadAllTasks,
   loadAllItems,
+  loadPlans,
   ReferenceIndex,
   createNote,
   saveTask,
@@ -72,6 +76,31 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           );
         }
 
+        // Automation filter — filter by automation eligibility status
+        if (query.automation) {
+          filtered = filtered.filter((task) => task.automation === query.automation);
+        }
+
+        // Plan filter — show only tasks derived from a given plan
+        if (query.plan) {
+          const plans = await loadPlans(ctx);
+          const plan = plans.find(
+            (p) => p._ulid === query.plan || p.slugs.includes(query.plan!)
+          );
+          if (plan) {
+            const derivedRefs = new Set(
+              plan.derived_tasks.map((r) => (r.startsWith('@') ? r.slice(1) : r))
+            );
+            filtered = filtered.filter(
+              (task) =>
+                derivedRefs.has(task._ulid) ||
+                task.slugs.some((s) => derivedRefs.has(s))
+            );
+          } else {
+            filtered = [];
+          }
+        }
+
         // AC: @api-contract ac-4 - Pagination
         const total = filtered.length;
         const offset = Number(query.offset) || 0;
@@ -85,12 +114,14 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           _ulid: task._ulid,
           slugs: task.slugs,
           title: task.title,
+          type: task.type || 'task',
           status: task.status,
           priority: task.priority,
           spec_ref: task.spec_ref,
           meta_ref: task.meta_ref,
           tags: task.tags,
           depends_on: task.depends_on || [],
+          automation: task.automation,
           notes_count: task.notes?.length || 0,
           todos_count: task.todos?.length || 0,
           started_at: task.started_at,
@@ -111,6 +142,8 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           status: t.Optional(t.Union([t.String(), t.Array(t.String())])),
           type: t.Optional(t.Union([t.String(), t.Array(t.String())])),
           tag: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+          automation: t.Optional(t.String()),
+          plan: t.Optional(t.String()),
           limit: t.Optional(t.String()),
           offset: t.Optional(t.String()),
         }),
@@ -150,19 +183,31 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         }
 
         // AC: @api-contract ac-5 - Return full task with notes, todos, dependencies
+        // AC: @ui-task-board ac-3 - Include type, description, blocked_by, vcs_refs, plan_ref, session_ref
         return {
           _ulid: task._ulid,
           slugs: task.slugs,
           title: task.title,
+          type: task.type || 'task',
           status: task.status,
           priority: task.priority,
           spec_ref: task.spec_ref,
           meta_ref: task.meta_ref,
           tags: task.tags,
           description: task.description,
+          derivation: task.derivation,
           depends_on: task.depends_on,
+          blocked_by: task.blocked_by || [],
+          context: task.context || [],
+          vcs_refs: (task.vcs_refs || []).map((v) =>
+            typeof v === 'string' ? v : v.type ? `${v.type}:${v.ref}` : v.ref
+          ),
+          plan_ref: task.plan_ref,
+          session_ref: task.session_id,
           notes: task.notes,
+          notes_count: task.notes?.length || 0,
           todos: task.todos,
+          todos_count: task.todos?.length || 0,
           started_at: task.started_at,
           completed_at: task.completed_at,
           cancelled_at: task.cancelled_at,
@@ -323,5 +368,158 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           content: t.String(),
         }),
       }
+    )
+
+    // AC: @ui-task-board ac-6 - Submit task for review
+    .post(
+      '/:ref/submit',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        const result = index.resolve(params.ref);
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Task reference "${params.ref}" not found`,
+          });
+        }
+
+        const task = tasks.find((t) => t._ulid === result.ulid);
+        if (!task) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not a task`,
+          });
+        }
+
+        if (task.status !== 'in_progress' && task.status !== 'needs_work') {
+          return errorResponse(409, {
+            error: 'invalid_transition',
+            message: `Cannot submit task with status "${task.status}". Must be in_progress or needs_work.`,
+            current: task.status,
+            valid_transitions: ['pending_review'],
+          });
+        }
+
+        const updatedTask: LoadedTask = { ...task, status: 'pending_review' };
+        await saveTask(ctx, updatedTask);
+        await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
+        await commitIfShadow(ctx.shadow, `task: submit ${params.ref}`);
+
+        pubsub.broadcast('tasks:updates', 'task_updated', {
+          ref: params.ref,
+          ulid: task._ulid,
+          action: 'submit',
+          status: 'pending_review',
+        }, projectContext.path);
+
+        return updatedTask;
+      },
+      { params: t.Object({ ref: t.String() }) }
+    )
+
+    // AC: @ui-task-board ac-6 - Complete task
+    .post(
+      '/:ref/complete',
+      async ({ params, body, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        const result = index.resolve(params.ref);
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Task reference "${params.ref}" not found`,
+          });
+        }
+
+        const task = tasks.find((t) => t._ulid === result.ulid);
+        if (!task) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not a task`,
+          });
+        }
+
+        const updatedTask: LoadedTask = {
+          ...task,
+          status: 'completed',
+          completed_at: new Date().toISOString(),
+          closed_reason: body.reason,
+        };
+        await saveTask(ctx, updatedTask);
+        await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
+        await commitIfShadow(ctx.shadow, `task: complete ${params.ref}`);
+
+        pubsub.broadcast('tasks:updates', 'task_updated', {
+          ref: params.ref,
+          ulid: task._ulid,
+          action: 'complete',
+          status: 'completed',
+        }, projectContext.path);
+
+        return updatedTask;
+      },
+      {
+        params: t.Object({ ref: t.String() }),
+        body: t.Object({ reason: t.String() }),
+      }
+    )
+
+    // AC: @ui-task-board ac-6 - Block task
+    .post(
+      '/:ref/block',
+      async ({ params, body, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        const result = index.resolve(params.ref);
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Task reference "${params.ref}" not found`,
+          });
+        }
+
+        const task = tasks.find((t) => t._ulid === result.ulid);
+        if (!task) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not a task`,
+          });
+        }
+
+        const author = getAuthor(ctx.config?.identity?.author);
+        const note = createNote(`Blocked: ${body.reason}`, author);
+
+        const updatedTask: LoadedTask = {
+          ...task,
+          status: 'blocked',
+          notes: [...(task.notes || []), note],
+        };
+        await saveTask(ctx, updatedTask);
+        await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
+        await commitIfShadow(ctx.shadow, `task: block ${params.ref}`);
+
+        pubsub.broadcast('tasks:updates', 'task_updated', {
+          ref: params.ref,
+          ulid: task._ulid,
+          action: 'block',
+          status: 'blocked',
+        }, projectContext.path);
+
+        return updatedTask;
+      },
+      {
+        params: t.Object({ ref: t.String() }),
+        body: t.Object({ reason: t.String() }),
+      }
     );
 }

package/dist/daemon/routes/validation.ts

@@ -218,7 +218,7 @@ export function createValidationRoutes(options: ValidationRouteOptions = {}) {
         refWarnings: result.refWarnings,
         orphans: result.orphans,
         completenessWarnings: result.completenessWarnings,
-        traitCycles: result.traitCycles,
+        traitCycles: result.traitCycleErrors,
       };
     })