@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/daemon/routes/inbox.ts

@@ -0,0 +1,164 @@
+/**
+ * Inbox API Routes
+ *
+ * REST endpoints for inbox item operations:
+ * - GET /api/inbox - list all items
+ * - POST /api/inbox - create item
+ * - DELETE /api/inbox/:ref - delete item
+ *
+ * AC Coverage:
+ * - ac-12: GET /api/inbox returns items ordered by created_at desc
+ * - ac-13: POST /api/inbox creates item with generated ULID
+ * - ac-14: DELETE /api/inbox/:ref removes item
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadInboxItems,
+  createInboxItem,
+  saveInboxItem,
+  deleteInboxItem,
+  findInboxItemByRef,
+  ReferenceIndex,
+  loadAllTasks,
+  loadAllItems,
+  type InboxItemInput,
+} from '../../parser/index.js';
+import { commitIfShadow } from '../../parser/shadow.js';
+import type { PubSubManager } from '../websocket/pubsub';
+
+interface InboxRouteOptions {
+  pubsub: PubSubManager;
+}
+
+export function createInboxRoutes(options: InboxRouteOptions) {
+  const { pubsub } = options;
+
+  return new Elysia({ prefix: '/api/inbox' })
+    // AC: @api-contract ac-12 - List inbox items ordered by created_at desc
+    .get('/', async ({ projectContext }) => {
+      // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+      const ctx = await initContext(projectContext.path);
+      const items = await loadInboxItems(ctx);
+
+      // AC: @api-contract ac-12 - Sort by created_at descending (newest first)
+      const sorted = [...items].sort(
+        (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+      );
+
+      return {
+        items: sorted,
+        total: sorted.length,
+      };
+    })
+
+    // AC: @api-contract ac-13 - Create inbox item
+    .post(
+      '/',
+      async ({ body, error: errorResponse, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+
+        // AC: @trait-api-endpoint ac-3 - Validate body
+        if (!body.text || typeof body.text !== 'string' || body.text.trim().length === 0) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'text',
+                message: 'Text is required and must be a non-empty string',
+              },
+            ],
+          });
+        }
+
+        // Create inbox item input
+        const input: InboxItemInput = {
+          text: body.text,
+          tags: body.tags,
+          added_by: body.added_by,
+        };
+
+        // AC: @api-contract ac-13 - Generate ULID and create item
+        const item = createInboxItem(input, ctx.config?.identity?.author);
+
+        // Save and commit
+        await saveInboxItem(ctx, item);
+        await commitIfShadow(ctx.shadow, `inbox: add item ${item._ulid}`);
+
+        // Broadcast update
+        // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
+        pubsub.broadcast('inbox:updates', 'inbox_item_created', {
+          ulid: item._ulid,
+        }, projectContext.path);
+
+        // AC: @api-contract ac-13 - Return item with generated ULID
+        return {
+          success: true,
+          item,
+        };
+      },
+      {
+        body: t.Object({
+          text: t.String(),
+          tags: t.Optional(t.Array(t.String())),
+          added_by: t.Optional(t.String()),
+        }),
+      }
+    )
+
+    // AC: @api-contract ac-14 - Delete inbox item
+    .delete(
+      '/: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 inboxItems = await loadInboxItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const specItems = await loadAllItems(ctx);
+        const index = new ReferenceIndex(tasks, specItems);
+
+        // Resolve ref
+        const result = index.resolve(params.ref);
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Inbox item reference "${params.ref}" not found`,
+            suggestion: 'Use kspec inbox list to find valid inbox item references',
+          });
+        }
+
+        // Verify it's an inbox item
+        const item = findInboxItemByRef(inboxItems, result.ulid);
+        if (!item) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not an inbox item`,
+          });
+        }
+
+        // AC: @api-contract ac-14 - Delete item
+        await deleteInboxItem(ctx, result.ulid);
+        await commitIfShadow(ctx.shadow, `inbox: delete ${params.ref}`);
+
+        // Broadcast update
+        // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
+        pubsub.broadcast('inbox:updates', 'inbox_item_deleted', {
+          ref: params.ref,
+          ulid: result.ulid,
+        }, projectContext.path);
+
+        // AC: @api-contract ac-14 - Return success confirmation
+        return {
+          success: true,
+          deleted: result.ulid,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    );
+}

package/dist/daemon/routes/items.ts

@@ -0,0 +1,322 @@
+/**
+ * Spec Item API Routes
+ *
+ * REST endpoints for spec item operations:
+ * - GET /api/items - list with filters and pagination
+ * - GET /api/items/:ref - get single item
+ * - GET /api/items/:ref/tasks - get linked tasks
+ *
+ * AC Coverage:
+ * - ac-8: GET /api/items returns array of spec items
+ * - ac-9: Type filter with multi-value support
+ * - ac-10: GET /api/items/:ref with full details
+ * - ac-11: GET /api/items/:ref/tasks via AlignmentIndex
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadAllItems,
+  loadAllTasks,
+  ReferenceIndex,
+  AlignmentIndex,
+  getCachedTestCoverage,
+  computeACCoverage,
+  type LoadedSpecItem,
+} from '../../parser/index.js';
+
+interface ItemsRouteOptions {}
+
+/**
+ * Compute parent ULIDs for items based on _path and _sourceFile.
+ * Items are nested when they share the same source file and
+ * one item's path is a prefix of another's path.
+ */
+function computeParentMap(items: LoadedSpecItem[]): Map<string, string | undefined> {
+  const parentMap = new Map<string, string | undefined>();
+
+  // Group items by source file
+  const byFile = new Map<string, LoadedSpecItem[]>();
+  for (const item of items) {
+    const file = item._sourceFile || '';
+    if (!byFile.has(file)) {
+      byFile.set(file, []);
+    }
+    byFile.get(file)!.push(item);
+  }
+
+  // For each file, determine parent relationships based on path
+  for (const [, fileItems] of byFile) {
+    // Sort by path length (shorter paths are potential parents)
+    const sorted = [...fileItems].sort((a, b) => {
+      const aLen = a._path?.length || 0;
+      const bLen = b._path?.length || 0;
+      return aLen - bLen;
+    });
+
+    for (const item of sorted) {
+      const itemPath = item._path;
+
+      if (!itemPath) {
+        // Root item in file - no parent
+        parentMap.set(item._ulid, undefined);
+        continue;
+      }
+
+      // Find the closest parent by matching path prefix
+      // Path format: "features[0].requirements[0]"
+      // Parent path: "features[0]" or undefined (root item)
+      const lastDot = itemPath.lastIndexOf('.');
+      const parentPath = lastDot > -1 ? itemPath.substring(0, lastDot) : undefined;
+
+      // Find parent item
+      let parentUlid: string | undefined;
+      if (parentPath === undefined) {
+        // Direct child of the root item (the item with no path)
+        const rootItem = fileItems.find(i => !i._path);
+        parentUlid = rootItem?._ulid;
+      } else {
+        // Find item with matching parent path
+        const parentItem = fileItems.find(i => i._path === parentPath);
+        parentUlid = parentItem?._ulid;
+      }
+
+      parentMap.set(item._ulid, parentUlid);
+    }
+  }
+
+  return parentMap;
+}
+
+export function createItemsRoutes(options: ItemsRouteOptions = {}) {
+  // No closure-scoped kspecDir needed - comes from middleware
+
+  return new Elysia({ prefix: '/api/items' })
+    // AC: @api-contract ac-8, ac-9 - List items with type filter
+    .get(
+      '/',
+      async ({ query, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const items = await loadAllItems(ctx);
+
+        // Compute parent relationships from path structure
+        const parentMap = computeParentMap(items);
+
+        // Apply filters
+        let filtered = items;
+
+        // AC: @api-contract ac-9 - Multi-value type filter
+        if (query.type) {
+          const typeFilters = Array.isArray(query.type) ? query.type : [query.type];
+          filtered = filtered.filter((item) => typeFilters.includes(item.type));
+        }
+
+        // Optional maturity filter (not in ACs but useful)
+        if (query.maturity) {
+          const maturityFilters = Array.isArray(query.maturity) ? query.maturity : [query.maturity];
+          filtered = filtered.filter((item) => {
+            if (typeof item.status === 'object' && item.status?.maturity) {
+              return maturityFilters.includes(item.status.maturity);
+            }
+            return false;
+          });
+        }
+
+        // Optional implementation filter (not in ACs but useful)
+        if (query.implementation) {
+          const implFilters = Array.isArray(query.implementation)
+            ? query.implementation
+            : [query.implementation];
+          filtered = filtered.filter((item) => {
+            if (typeof item.status === 'object' && item.status?.implementation) {
+              return implFilters.includes(item.status.implementation);
+            }
+            return false;
+          });
+        }
+
+        // Tag filter (not in ACs but useful)
+        if (query.tag) {
+          const tagFilters = Array.isArray(query.tag) ? query.tag : [query.tag];
+          filtered = filtered.filter((item) =>
+            item.tags?.some((t) => tagFilters.includes(t))
+          );
+        }
+
+        // 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-8 - Return spec items (modules, features, requirements)
+        const result = paginated.map((item) => ({
+          _ulid: item._ulid,
+          slugs: item.slugs,
+          title: item.title,
+          type: item.type,
+          status: item.status,
+          tags: item.tags,
+          parent: parentMap.get(item._ulid),
+          created_at: item.created_at,
+          acceptance_criteria_count: item.acceptance_criteria?.length || 0,
+        }));
+
+        // AC: @trait-api-endpoint ac-4 - Return pagination wrapper
+        return {
+          items: result,
+          total,
+          offset,
+          limit,
+        };
+      },
+      {
+        query: t.Object({
+          type: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+          maturity: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+          implementation: 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-10 - Get single item 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 items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const index = new ReferenceIndex(tasks, items);
+
+        // Compute parent relationships from path structure
+        const parentMap = computeParentMap(items);
+
+        // AC: @api-contract ac-10, @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: `Item reference "${params.ref}" not found`,
+            suggestion: 'Use kspec item list or kspec search to find valid item references',
+          });
+        }
+
+        // Find the item
+        const item = items.find((i) => i._ulid === result.ulid);
+        if (!item) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not a spec item`,
+            suggestion: 'This reference might point to a task instead',
+          });
+        }
+
+        // AC: @web-dashboard ac-15 - Compute test coverage for acceptance criteria
+        // Uses cached coverage scan for performance (avoids re-scanning on every request)
+        let acceptanceCriteriaWithCoverage = item.acceptance_criteria;
+        if (item.acceptance_criteria && item.acceptance_criteria.length > 0) {
+          try {
+            const coveredACs = await getCachedTestCoverage(projectContext.path);
+            acceptanceCriteriaWithCoverage = computeACCoverage(item, coveredACs);
+          } catch (err) {
+            // Coverage scan failed - leave as undefined
+            console.warn('AC coverage scan failed:', err);
+          }
+        }
+
+        // AC: @api-contract ac-10 - Return full item with acceptance_criteria, traits, relationships
+        return {
+          _ulid: item._ulid,
+          slugs: item.slugs,
+          title: item.title,
+          type: item.type,
+          status: item.status,
+          tags: item.tags,
+          parent: parentMap.get(item._ulid),
+          description: item.description,
+          acceptance_criteria: acceptanceCriteriaWithCoverage,
+          traits: item.traits,
+          relationships: item.relationships,
+          created_at: item.created_at,
+          _sourceFile: item._sourceFile,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    )
+
+    // AC: @api-contract ac-11 - Get tasks linked to spec item
+    .get(
+      '/:ref/tasks',
+      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 items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const refIndex = new ReferenceIndex(tasks, items);
+        const alignIndex = new AlignmentIndex(tasks, items);
+        alignIndex.buildLinks(refIndex);
+
+        // Resolve ref
+        const result = refIndex.resolve(params.ref);
+
+        if (!result.ok) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Item reference "${params.ref}" not found`,
+            suggestion: 'Use kspec item list to find valid item references',
+          });
+        }
+
+        const item = items.find((i) => i._ulid === result.ulid);
+        if (!item) {
+          return errorResponse(404, {
+            error: 'not_found',
+            message: `Reference "${params.ref}" is not a spec item`,
+          });
+        }
+
+        // AC: @api-contract ac-11 - Get tasks via AlignmentIndex
+        const linkedTasks = alignIndex.getTasksForSpec(result.ulid);
+
+        // Return tasks with summary info
+        const result_items = linkedTasks.map((task) => ({
+          _ulid: task._ulid,
+          slugs: task.slugs,
+          title: task.title,
+          type: task.type || 'task',
+          status: task.status,
+          priority: task.priority,
+          spec_ref: task.spec_ref,
+          tags: task.tags || [],
+          depends_on: task.depends_on || [],
+          started_at: task.started_at,
+          completed_at: task.completed_at,
+          created_at: task.created_at,
+          notes_count: task.notes?.length || 0,
+          todos_count: task.todos?.length || 0,
+        }));
+
+        return {
+          items: result_items,
+          total: result_items.length,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    );
+}

package/dist/daemon/routes/meta.ts

@@ -0,0 +1,118 @@
+/**
+ * Meta API Routes
+ *
+ * REST endpoints for meta operations:
+ * - GET /api/meta/session - get session context
+ * - GET /api/meta/agents - list agents
+ * - GET /api/meta/workflows - list workflows
+ * - GET /api/meta/observations - list observations with filter
+ *
+ * AC Coverage:
+ * - ac-15: GET /api/meta/session returns session context
+ * - ac-16: GET /api/meta/agents returns all agents
+ * - ac-17: GET /api/meta/workflows returns all workflows
+ * - ac-18: GET /api/meta/observations with filter
+ */
+
+import { Elysia, t } from 'elysia';
+import {
+  initContext,
+  loadMetaContext,
+  loadSessionContext,
+} from '../../parser/index.js';
+
+interface MetaRouteOptions {}
+
+export function createMetaRoutes(options: MetaRouteOptions = {}) {
+  // No closure-scoped kspecDir needed - comes from middleware
+
+  return new Elysia({ prefix: '/api/meta' })
+    // AC: @api-contract ac-15 - Get session context
+    .get('/session', async ({ projectContext }) => {
+      // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+      const ctx = await initContext(projectContext.path);
+      const session = await loadSessionContext(ctx);
+
+      // AC: @api-contract ac-15 - Return session context (focus, threads, questions)
+      return {
+        focus: session.focus,
+        threads: session.threads || [],
+        questions: session.questions || [],
+        updated_at: session.updated_at,
+      };
+    })
+
+    // AC: @api-contract ac-16 - List agents
+    .get('/agents', async ({ projectContext }) => {
+      // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+      const ctx = await initContext(projectContext.path);
+      const meta = await loadMetaContext(ctx);
+
+      // AC: @api-contract ac-16 - Return all defined agents
+      const agents = meta.agents;
+
+      return {
+        items: agents,
+        total: agents.length,
+      };
+    })
+
+    // AC: @api-contract ac-17 - List workflows
+    .get('/workflows', async ({ projectContext }) => {
+      // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+      const ctx = await initContext(projectContext.path);
+      const meta = await loadMetaContext(ctx);
+
+      // AC: @api-contract ac-17 - Return all defined workflows
+      const workflows = meta.workflows;
+
+      return {
+        items: workflows,
+        total: workflows.length,
+      };
+    })
+
+    // AC: @api-contract ac-18 - List observations with filter
+    .get(
+      '/observations',
+      async ({ query, projectContext }) => {
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const meta = await loadMetaContext(ctx);
+
+        // Start with all observations
+        let filtered = meta.observations || [];
+
+        // AC: @api-contract ac-18 - Filter by resolved status
+        if (query.resolved !== undefined) {
+          const resolvedFilter = query.resolved === 'true';
+          filtered = filtered.filter((obs) => {
+            const isResolved = !!obs.resolved_at;
+            return isResolved === resolvedFilter;
+          });
+        }
+
+        // Optional type filter (not in ACs but useful)
+        if (query.type) {
+          const typeFilters = Array.isArray(query.type) ? query.type : [query.type];
+          filtered = filtered.filter((obs) => typeFilters.includes(obs.type));
+        }
+
+        // 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()
+        );
+
+        return {
+          items: sorted,
+          total: sorted.length,
+        };
+      },
+      {
+        query: t.Object({
+          resolved: t.Optional(t.String()),
+          type: t.Optional(t.Union([t.String(), t.Array(t.String())])),
+        }),
+      }
+    );
+}