@kynetic-ai/spec 0.11.0 → 0.12.0

package/dist/daemon/routes/ref-resolution.ts

@@ -0,0 +1,119 @@
+/**
+ * Reference Resolution Utilities
+ *
+ * Server-side resolution of @references to display-ready metadata.
+ * Used by API routes to include resolved titles alongside raw refs.
+ *
+ * AC: @ui-api-ref-resolution ac-1, ac-2, ac-3
+ */
+
+import type { ReferenceIndex } from '../../parser/index.js';
+
+/**
+ * Resolved metadata for a single-valued reference.
+ * AC: @ui-api-ref-resolution ac-1
+ */
+export interface ResolvedRef {
+  ref: string;
+  title: string | null;
+}
+
+/**
+ * Resolved metadata for an array reference entry with status.
+ * AC: @ui-api-ref-resolution ac-2
+ */
+export interface ResolvedRefEntry {
+  ref: string;
+  title: string | null;
+  status: string | null;
+}
+
+/**
+ * Lightweight index entry for the ref index endpoint.
+ * AC: @ui-api-ref-resolution ac-4, ac-5
+ */
+export interface RefIndexEntry {
+  title: string;
+  type: string;
+  status?: string;
+}
+
+/**
+ * Resolve a single-valued reference to its title.
+ * Returns null title if the ref cannot be resolved (ac-3).
+ *
+ * AC: @ui-api-ref-resolution ac-1, ac-3
+ */
+export function resolveRefTitle(
+  index: ReferenceIndex,
+  ref: string | undefined | null,
+): string | null {
+  if (!ref) return null;
+  const result = index.resolve(ref);
+  if (!result.ok) return null;
+  const item = result.item as { title?: string };
+  return item.title ?? null;
+}
+
+/**
+ * Resolve an array of references to entries with title and status.
+ * Invalid/deleted refs get null title but preserve the raw ref (ac-3).
+ *
+ * AC: @ui-api-ref-resolution ac-2, ac-3
+ */
+export function resolveRefEntries(
+  index: ReferenceIndex,
+  refs: string[] | undefined | null,
+): ResolvedRefEntry[] {
+  if (!refs || refs.length === 0) return [];
+  return refs.map((ref) => {
+    const result = index.resolve(ref);
+    if (!result.ok) {
+      return { ref, title: null, status: null };
+    }
+    const item = result.item as { title?: string; status?: string };
+    return {
+      ref,
+      title: item.title ?? null,
+      status: item.status ?? null,
+    };
+  });
+}
+
+/**
+ * Build a lightweight ref index map for the index endpoint.
+ * Includes both ULID and slug keys for each entity.
+ *
+ * AC: @ui-api-ref-resolution ac-4, ac-5
+ */
+export function buildRefIndex(
+  index: ReferenceIndex,
+): Record<string, RefIndexEntry> {
+  const result: Record<string, RefIndexEntry> = {};
+
+  for (const ulid of index.getAllUlids()) {
+    const item = index.getByUlid(ulid);
+    if (!item) continue;
+
+    const typed = item as { title?: string; type?: string; status?: string; slugs?: string[] };
+    if (!typed.title) continue;
+
+    const entry: RefIndexEntry = {
+      title: typed.title,
+      type: typed.type ?? 'unknown',
+      ...(typed.status ? { status: typed.status } : {}),
+    };
+
+    // Index by ULID
+    result[ulid] = entry;
+
+    // Index by slugs
+    if (typed.slugs) {
+      for (const slug of typed.slugs) {
+        result[slug] = entry;
+      }
+    }
+  }
+
+  return result;
+}

package/dist/daemon/routes/refs.ts

@@ -0,0 +1,42 @@
+/**
+ * Ref Index API Route
+ *
+ * Lightweight endpoint for resolving arbitrary refs to display metadata.
+ * Returns a map of all resolvable refs (tasks, items, traits) with
+ * title, type, and status. Both ULID and slug keys are included.
+ *
+ * AC Coverage:
+ * - @ui-api-ref-resolution ac-4: Returns map of all resolvable refs with display metadata
+ * - @ui-api-ref-resolution ac-5: Payload is significantly smaller than full entity lists
+ * - @trait-api-endpoint ac-1: Returns 2xx with JSON body
+ * - @trait-api-endpoint ac-6: Includes X-Request-Id header (via middleware)
+ */
+
+import { Elysia } from 'elysia';
+import {
+  initContext,
+  loadAllTasks,
+  loadAllItems,
+  loadPlans,
+  ReferenceIndex,
+} from '../../parser/index.js';
+import { buildRefIndex } from './ref-resolution.js';
+
+export function createRefsRoutes() {
+  return new Elysia({ prefix: '/api/refs' })
+
+    // AC: @ui-api-ref-resolution ac-4, ac-5 - Lightweight ref index endpoint
+    // AC: @trait-api-endpoint ac-1 - Returns 2xx with JSON body
+    .get('/', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const [tasks, items, plans] = await Promise.all([
+        loadAllTasks(ctx),
+        loadAllItems(ctx),
+        loadPlans(ctx),
+      ]);
+      const index = new ReferenceIndex(tasks, items, [], plans);
+      const refs = buildRefIndex(index);
+
+      return { refs };
+    });
+}

package/dist/daemon/routes/session-related.ts

@@ -0,0 +1,140 @@
+import {
+  AlignmentIndex,
+  ReferenceIndex,
+  type LoadedSpecItem,
+  type LoadedTask,
+} from '../../parser/index.js';
+import { getSessionCache } from '../../sessions/cache.js';
+import type { SessionLogSummary } from '../../sessions/store.js';
+
+interface RelatedSessionsNotFound {
+  error: 'not_found';
+  message: string;
+  suggestion: string;
+}
+
+function sortSessions(sessions: SessionLogSummary[]): SessionLogSummary[] {
+  return [...sessions].sort(
+    (a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime()
+  );
+}
+
+function buildTaskRefSet(task: Pick<LoadedTask, '_ulid' | 'slugs'>): Set<string> {
+  const refs = new Set<string>([task._ulid, `@${task._ulid}`]);
+  for (const slug of task.slugs) {
+    refs.add(slug);
+    refs.add(`@${slug}`);
+  }
+  return refs;
+}
+
+function filterSessionsByTaskRefs(
+  sessions: SessionLogSummary[],
+  taskRefs: Set<string>
+): SessionLogSummary[] {
+  return sessions.filter((session) => {
+    if (!session.task_id) return false;
+    const taskId = session.task_id.startsWith('@')
+      ? session.task_id.slice(1)
+      : session.task_id;
+    return taskRefs.has(taskId) || taskRefs.has(session.task_id);
+  });
+}
+
+export async function getRelatedSessionsForTask(params: {
+  items: LoadedSpecItem[];
+  tasks: LoadedTask[];
+  taskRef: string;
+  sessionsDir: string;
+}): Promise<
+  | { sessions: SessionLogSummary[]; task: LoadedTask }
+  | { error: RelatedSessionsNotFound }
+> {
+  const { items, tasks, taskRef, sessionsDir } = params;
+  const refIndex = new ReferenceIndex(tasks, items);
+  const resolved = refIndex.resolve(taskRef);
+
+  if (!resolved.ok) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Task reference "${taskRef}" not found`,
+        suggestion: 'Use GET /api/tasks or kspec task list to find valid task references',
+      },
+    };
+  }
+
+  const task = tasks.find((candidate) => candidate._ulid === resolved.ulid);
+  if (!task) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Reference "${taskRef}" is not a task`,
+        suggestion: 'This reference might point to a spec item instead',
+      },
+    };
+  }
+
+  const sessionCache = getSessionCache(sessionsDir);
+  const sessions = await sessionCache.getAll(sessionsDir);
+  const filtered = filterSessionsByTaskRefs(sessions, buildTaskRefSet(task));
+
+  return {
+    task,
+    sessions: sortSessions(filtered),
+  };
+}
+
+export async function getRelatedSessionsForItem(params: {
+  itemRef: string;
+  items: LoadedSpecItem[];
+  tasks: LoadedTask[];
+  sessionsDir: string;
+}): Promise<
+  | { item: LoadedSpecItem; sessions: SessionLogSummary[] }
+  | { error: RelatedSessionsNotFound }
+> {
+  const { itemRef, items, tasks, sessionsDir } = params;
+  const refIndex = new ReferenceIndex(tasks, items);
+  const alignmentIndex = new AlignmentIndex(tasks, items);
+  alignmentIndex.buildLinks(refIndex);
+
+  const resolved = refIndex.resolve(itemRef);
+  if (!resolved.ok) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Item reference "${itemRef}" not found`,
+        suggestion: 'Use GET /api/items or kspec item list to find valid item references',
+      },
+    };
+  }
+
+  const item = items.find((candidate) => candidate._ulid === resolved.ulid);
+  if (!item) {
+    return {
+      error: {
+        error: 'not_found',
+        message: `Reference "${itemRef}" is not a spec item`,
+        suggestion: 'This reference might point to a task instead',
+      },
+    };
+  }
+
+  const linkedTasks = alignmentIndex.getTasksForSpec(resolved.ulid);
+  const taskRefs = new Set<string>();
+  for (const task of linkedTasks) {
+    for (const ref of buildTaskRefSet(task)) {
+      taskRefs.add(ref);
+    }
+  }
+
+  const sessionCache = getSessionCache(sessionsDir);
+  const sessions = await sessionCache.getAll(sessionsDir);
+  const filtered = filterSessionsByTaskRefs(sessions, taskRefs);
+
+  return {
+    item,
+    sessions: sortSessions(filtered),
+  };
+}