@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/daemon/routes/projects.ts

@@ -0,0 +1,162 @@
+/**
+ * Projects API Routes
+ *
+ * REST endpoints for project management operations:
+ * - GET /api/projects - list all registered projects
+ * - POST /api/projects - manually register a project
+ * - DELETE /api/projects/:encodedPath - unregister a project
+ *
+ * All endpoints return JSON responses.
+ *
+ * AC Coverage:
+ * - ac-28: GET /api/projects returns list with paths, registration time, watcher status
+ * - ac-29: POST /api/projects with {path: string} body for manual registration
+ * - ac-30: DELETE /api/projects/:encodedPath unregisters and stops watcher
+ */
+
+import { Elysia, t } from 'elysia';
+import { isAbsolute } from 'path';
+import type { ProjectContextManager } from '../project-context';
+
+interface ProjectsRouteOptions {
+  projectManager: ProjectContextManager;
+}
+
+export function createProjectsRoutes(options: ProjectsRouteOptions) {
+  const { projectManager } = options;
+
+  return new Elysia({ prefix: '/api/projects' })
+    // AC: @multi-directory-daemon ac-28 - List registered projects
+    .get('/', async () => {
+      const projects = projectManager.listProjects();
+
+      // AC: @multi-directory-daemon ac-28 - Include paths, registration time, watcher status
+      return {
+        projects: projects.map(project => ({
+          path: project.path,
+          registeredAt: project.registeredAt.toISOString(),
+          watcherStatus: project.watcherActive ? 'active' : 'stopped',
+        })),
+        total: projects.length,
+      };
+    })
+
+    // AC: @multi-directory-daemon ac-29 - Manual project registration
+    .post(
+      '/',
+      async ({ body, error: errorResponse }) => {
+        // AC: @multi-directory-daemon ac-29 - Accept {path: string} body
+        // Validate path is provided
+        if (!body.path || typeof body.path !== 'string' || body.path.trim().length === 0) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'path',
+                message: 'Path is required and must be a non-empty string',
+              },
+            ],
+          });
+        }
+
+        // AC: @multi-directory-daemon ac-6 - Path must be absolute
+        if (!isAbsolute(body.path)) {
+          return errorResponse(400, {
+            error: 'Path must be absolute',
+          });
+        }
+
+        // AC: @multi-directory-daemon ac-7 - Reject parent traversal (..)
+        if (body.path.includes('..')) {
+          return errorResponse(400, {
+            error: 'Path must not contain parent traversal',
+          });
+        }
+
+        try {
+          // AC: @multi-directory-daemon ac-29 - Use ProjectContextManager.registerProject()
+          const context = projectManager.registerProject(body.path);
+
+          // Start watcher for the registered project
+          try {
+            await projectManager.startWatcher(body.path);
+          } catch (error: unknown) {
+            // AC: @multi-directory-daemon ac-19 - Handle OS limits
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('resource limit')) {
+              return errorResponse(503, {
+                error: 'Unable to watch project - resource limit reached',
+              });
+            }
+            throw error;
+          }
+
+          return {
+            success: true,
+            project: {
+              path: context.path,
+              registeredAt: context.registeredAt.toISOString(),
+              watcherStatus: context.watcherActive ? 'active' : 'stopped',
+            },
+          };
+        } catch (error: unknown) {
+          const message = error instanceof Error ? error.message : String(error);
+          const code = error instanceof Error && 'code' in error ? (error as NodeJS.ErrnoException).code : undefined;
+
+          // AC: @multi-directory-daemon ac-5 - Invalid project (no .kspec/)
+          if (message.includes('.kspec/ not found')) {
+            return errorResponse(400, {
+              error: `Invalid kspec project - .kspec/ not found at ${body.path}`,
+            });
+          }
+
+          // AC: @multi-directory-daemon ac-8b - Permission denied
+          if (code === 'EACCES' || code === 'EPERM') {
+            return errorResponse(403, {
+              error: `Permission denied - cannot read ${body.path}`,
+            });
+          }
+
+          // Generic error
+          return errorResponse(500, {
+            error: message || 'Failed to register project',
+          });
+        }
+      },
+      {
+        body: t.Object({
+          path: t.String(),
+        }),
+      }
+    )
+
+    // AC: @multi-directory-daemon ac-30 - Unregister project
+    .delete('/:encodedPath', async ({ params, error: errorResponse }) => {
+      // AC: @multi-directory-daemon ac-30 - Decode path from URL parameter
+      const projectPath = decodeURIComponent(params.encodedPath);
+
+      // Validate project exists
+      if (!projectManager.hasProject(projectPath)) {
+        return errorResponse(404, {
+          error: `Project not registered: ${projectPath}`,
+        });
+      }
+
+      try {
+        // AC: @multi-directory-daemon ac-30 - Stop file watcher
+        await projectManager.stopWatcher(projectPath);
+
+        // AC: @multi-directory-daemon ac-30 - Unregister project
+        projectManager.unregisterProject(projectPath);
+
+        return {
+          success: true,
+          message: `Project unregistered: ${projectPath}`,
+        };
+      } catch (error: unknown) {
+        return errorResponse(500, {
+          error: error instanceof Error ? error.message : 'Failed to unregister project',
+        });
+      }
+    });
+}

package/dist/daemon/routes/tasks.ts

@@ -0,0 +1,327 @@
+/**
+ * Task API Routes
+ *
+ * REST endpoints for task operations:
+ * - GET /api/tasks - list with filters and pagination
+ * - GET /api/tasks/:ref - get single task
+ * - POST /api/tasks/:ref/start - start task
+ * - POST /api/tasks/:ref/note - add note
+ *
+ * AC Coverage:
+ * - ac-2: GET /api/tasks returns array with status, priority, spec_ref, notes count
+ * - ac-3: Status filter with multi-value support
+ * - ac-4: Pagination with {items, total, offset, limit} wrapper
+ * - 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
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadAllTasks,
+  loadAllItems,
+  ReferenceIndex,
+  createNote,
+  saveTask,
+  getAuthor,
+  syncSpecImplementationStatus,
+  type LoadedTask,
+} from '../../parser/index.js';
+import { commitIfShadow } from '../../parser/shadow.js';
+import type { PubSubManager } from '../websocket/pubsub';
+
+interface TasksRouteOptions {
+  pubsub: PubSubManager;
+}
+
+export function createTasksRoutes(options: TasksRouteOptions) {
+  const { pubsub } = options;
+
+  return new Elysia({ prefix: '/api/tasks' })
+    // AC: @api-contract ac-2, ac-3, ac-4 - List tasks with filters and pagination
+    .get(
+      '/',
+      async ({ query, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const specItems = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, specItems);
+
+        // Apply filters
+        let filtered = tasks;
+
+        // AC: @api-contract ac-3 - Multi-value status filter
+        if (query.status) {
+          const statusFilters = Array.isArray(query.status) ? query.status : [query.status];
+          filtered = filtered.filter((task) => statusFilters.includes(task.status));
+        }
+
+        // Type filter (optional, not in ACs but useful)
+        if (query.type) {
+          const typeFilters = Array.isArray(query.type) ? query.type : [query.type];
+          filtered = filtered.filter((task) => task.type && typeFilters.includes(task.type));
+        }
+
+        // Tag filter (optional, not in ACs but useful)
+        if (query.tag) {
+          const tagFilters = Array.isArray(query.tag) ? query.tag : [query.tag];
+          filtered = filtered.filter((task) =>
+            task.tags?.some((t) => tagFilters.includes(t))
+          );
+        }
+
+        // AC: @api-contract ac-4 - Pagination
+        const total = filtered.length;
+        const offset = Number(query.offset) || 0;
+        const limit = Number(query.limit) || total;
+
+        const paginated = filtered.slice(offset, offset + limit);
+
+        // AC: @api-contract ac-2 - Return with status, priority, spec_ref, notes count
+        // AC: @web-dashboard ac-1 - Include depends_on for blocked task computation
+        const items = paginated.map((task) => ({
+          _ulid: task._ulid,
+          slugs: task.slugs,
+          title: task.title,
+          status: task.status,
+          priority: task.priority,
+          spec_ref: task.spec_ref,
+          meta_ref: task.meta_ref,
+          tags: task.tags,
+          depends_on: task.depends_on || [],
+          notes_count: task.notes?.length || 0,
+          todos_count: task.todos?.length || 0,
+          started_at: task.started_at,
+          completed_at: task.completed_at,
+          created_at: task.created_at,
+        }));
+
+        // AC: @api-contract ac-4, @trait-api-endpoint ac-4 - Return pagination wrapper
+        return {
+          items,
+          total,
+          offset,
+          limit,
+        };
+      },
+      {
+        query: t.Object({
+          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())])),
+          limit: t.Optional(t.String()),
+          offset: t.Optional(t.String()),
+        }),
+      }
+    )
+
+    // AC: @api-contract ac-5 - Get single task by ref
+    .get(
+      '/:ref',
+      async ({ params, error: errorResponse, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        // AC: @api-contract ac-5, @trait-api-endpoint ac-2 - Resolve ref via ReferenceIndex
+        const result = index.resolve(params.ref);
+
+        if (!result.ok) {
+          // AC: @trait-api-endpoint ac-2 - Return 404 with error details
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Task reference "${params.ref}" not found`,
+            suggestion: 'Use kspec task list or kspec search to find valid task references',
+          });
+        }
+
+        // Find the task
+        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`,
+            suggestion: 'This reference might point to a spec item instead',
+          });
+        }
+
+        // AC: @api-contract ac-5 - Return full task with notes, todos, dependencies
+        return {
+          _ulid: task._ulid,
+          slugs: task.slugs,
+          title: task.title,
+          status: task.status,
+          priority: task.priority,
+          spec_ref: task.spec_ref,
+          meta_ref: task.meta_ref,
+          tags: task.tags,
+          description: task.description,
+          depends_on: task.depends_on,
+          notes: task.notes,
+          todos: task.todos,
+          started_at: task.started_at,
+          completed_at: task.completed_at,
+          cancelled_at: task.cancelled_at,
+          closed_reason: task.closed_reason,
+          automation: task.automation,
+          created_at: task.created_at,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    )
+
+    // AC: @api-contract ac-6 - Start task
+    .post(
+      '/:ref/start',
+      async ({ params, error: errorResponse, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        // Resolve ref
+        const result = index.resolve(params.ref);
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Task reference "${params.ref}" not found`,
+            suggestion: 'Use kspec task list to find valid task references',
+          });
+        }
+
+        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`,
+          });
+        }
+
+        // AC: @api-contract ac-6 - Transition to in_progress
+        if (task.status === 'in_progress') {
+          return errorResponse(409, {
+            error: 'invalid_transition',
+            message: 'Task is already in_progress',
+            current: task.status,
+            valid_transitions: ['blocked', 'pending_review', 'completed', 'cancelled'],
+          });
+        }
+
+        // Update task status
+        const updatedTask: LoadedTask = {
+          ...task,
+          status: 'in_progress',
+          started_at: task.started_at || new Date().toISOString(),
+        };
+
+        // Save and commit
+        await saveTask(ctx, updatedTask);
+        await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
+        await commitIfShadow(ctx.shadow, `task: start ${params.ref}`);
+
+        // AC: @api-contract ac-6, @trait-api-endpoint ac-5 - WebSocket broadcast
+        // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
+        pubsub.broadcast('tasks:updates', 'task_updated', {
+          ref: params.ref,
+          ulid: task._ulid,
+          action: 'start',
+          status: 'in_progress',
+        }, projectContext.path);
+
+        // AC: @api-contract ac-6 - Return updated task
+        return updatedTask;
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    )
+
+    // AC: @api-contract ac-7 - Add note to task
+    .post(
+      '/:ref/note',
+      async ({ params, body, error: errorResponse, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        // Resolve ref
+        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`,
+          });
+        }
+
+        // AC: @trait-api-endpoint ac-3 - Validate body
+        if (!body.content || typeof body.content !== 'string') {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'content',
+                message: 'Content is required and must be a string',
+              },
+            ],
+          });
+        }
+
+        // AC: @api-contract ac-7 - Append note
+        const author = getAuthor(ctx.config?.identity?.author);
+        const note = createNote(body.content, author);
+
+        const updatedTask: LoadedTask = {
+          ...task,
+          notes: [...(task.notes || []), note],
+        };
+
+        // AC: @api-contract ac-7, @trait-api-endpoint ac-5 - Shadow commit
+        await saveTask(ctx, updatedTask);
+        await commitIfShadow(ctx.shadow, `task: add note to ${params.ref}`);
+
+        // AC: @api-contract ac-7 - WebSocket broadcast
+        // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
+        pubsub.broadcast('tasks:updates', 'task_updated', {
+          ref: params.ref,
+          ulid: task._ulid,
+          action: 'note_added',
+          note_ulid: note._ulid,
+        }, projectContext.path);
+
+        return {
+          success: true,
+          note,
+          task: updatedTask,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+        body: t.Object({
+          content: t.String(),
+        }),
+      }
+    );
+}