@critical-path/server 0.23.4 → 0.24.1

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from './router.js';
-export * from './adapters/next.js';
-export * from './adapters/sveltekit.js';
-export * from './adapters/universal.js';
-export * from './openapi.js';

package/src/openapi.test.ts

@@ -1,102 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { CriticalPathRouter } from './router.js';
-import { ROUTES, buildOpenApiDocument } from './openapi.js';
-
-const base = 'http://localhost:3000/api/critical-path';
-
-describe('OpenAPI document', () => {
-  it('documents every route the router serves, with matching response envelopes', async () => {
-    const router = new CriticalPathRouter();
-    const engine = router.engine;
-    const project = await engine.createProject({ key: 'OAS', name: 'OpenAPI' });
-    const task = await engine.createTask({ projectId: project.id, title: 'Task' });
-    const workflow = await engine.createWorkflow({ name: 'WF', statuses: [], transitions: [] });
-    const team = await engine.createTeam({ name: 'Team', memberIds: [] });
-    const container = await engine.createContainer({ projectId: project.id, name: 'Epic' });
-    const deliverable = await engine.createDeliverable({ projectId: project.id, title: 'Cut' });
-    const iteration = await engine.createIteration({ projectId: project.id, name: 'S1', status: 'planning' });
-    const comment = await engine.addComment({ taskId: task.id, content: 'hi', authorId: 'u1' });
-    const attachment = await engine.createAttachment({
-      taskId: task.id,
-      uploaderId: 'u1',
-      filename: 'a.md',
-      mimeType: 'text/markdown',
-      sizeBytes: 1,
-      url: 'https://example.com/a.md'
-    });
-
-    const { webhook } = await engine.createWebhook({ name: 'Hook', url: 'https://hooks.example.com/oas', events: ['*'] });
-
-    const otherTask = await engine.createTask({ projectId: project.id, title: 'Upstream' });
-    const dependency = await engine.addDependency({ taskId: task.id, dependsOnTaskId: otherTask.id, type: 'blocking' });
-
-    const ids: Record<string, string> = {
-      dependencyId: dependency.id,
-      webhookId: webhook.id,
-      projectId: project.id,
-      taskId: task.id,
-      workflowId: workflow.id,
-      teamId: team.id,
-      containerId: container.id,
-      deliverableId: deliverable.id,
-      iterationId: iteration.id,
-      commentId: comment.id,
-      attachmentId: attachment.id
-    };
-    const query: Record<string, string> = { projectId: project.id, taskId: task.id, emoji: '👍', userId: 'u1' };
-
-    // Deletes run last so earlier routes still have data; the project goes last of all.
-    const ordered = [...ROUTES].sort((a, b) => {
-      const rank = (r: (typeof ROUTES)[number]) => (r.method === 'delete' ? (r.path === '/projects/{projectId}' ? 2 : 1) : 0);
-      return rank(a) - rank(b);
-    });
-
-    for (const route of ordered) {
-      const path = route.path.replace(/\{(\w+)\}/g, (_, name) => ids[name]);
-      const params = new URLSearchParams();
-      for (const q of route.query ?? []) {
-        const name = q.replace(/!$/, '');
-        if (query[name]) params.set(name, query[name]);
-      }
-      const res = await router.handleRequest(
-        new Request(`${base}${path}${params.size ? `?${params}` : ''}`, {
-          method: route.method.toUpperCase(),
-          headers: { 'Content-Type': 'application/json' },
-          ...(route.method === 'post' || route.method === 'patch' ? { body: '{}' } : {})
-        })
-      );
-      const body = await res.json();
-      const label = `${route.method.toUpperCase()} ${route.path}`;
-      expect(String(body.error ?? ''), label).not.toMatch(/^Route not found/);
-      if (res.status < 300 && route.responseKey) {
-        expect(body, label).toHaveProperty(route.responseKey);
-      }
-    }
-  });
-
-  it('serves the document at /openapi.json with request bodies from the validation schemas', async () => {
-    const router = new CriticalPathRouter();
-    const res = await router.handleRequest(new Request(`${base}/openapi.json`));
-    expect(res.status).toBe(200);
-    const doc = await res.json();
-
-    expect(doc.openapi).toBe('3.1.0');
-    expect(doc.servers[0].url).toBe('http://localhost:3000/api/critical-path');
-    const createTask = doc.paths['/tasks'].post.requestBody.content['application/json'].schema;
-    expect(createTask.required).toEqual(expect.arrayContaining(['projectId', 'title']));
-    expect(createTask.properties).not.toHaveProperty('id');
-    expect(doc.paths['/tasks/{taskId}/dependencies'].post.responses).toHaveProperty('409');
-  });
-
-  it('respects requireAuth', async () => {
-    const router = new CriticalPathRouter(undefined, { requireAuth: true });
-    const res = await router.handleRequest(new Request(`${base}/openapi.json`));
-    expect(res.status).toBe(401);
-  });
-
-  it('can be built without a router for static publishing', () => {
-    const doc = buildOpenApiDocument({ serverUrl: 'https://api.example.com/pm', version: '2.0.0' }) as any;
-    expect(doc.info.version).toBe('2.0.0');
-    expect(Object.keys(doc.paths).length).toBeGreaterThan(30);
-  });
-});

package/src/openapi.ts

@@ -1,186 +0,0 @@
-import { zodToJsonSchema } from 'zod-to-json-schema';
-import * as schemas from '@critical-path/core/schemas';
-
-type Method = 'get' | 'post' | 'patch' | 'delete';
-
-interface RouteDoc {
-  method: Method;
-  path: string;
-  summary: string;
-  tag: string;
-  /** Query parameters; names ending in `!` are required. */
-  query?: string[];
-  body?: { safeParse(data: unknown): unknown };
-  /** Key of the JSON response envelope, e.g. `task` for `{ "task": { ... } }`. */
-  responseKey?: string;
-  status?: number;
-}
-
-/** Every route served by `CriticalPathRouter`. Kept in sync by the route drift test. */
-export const ROUTES: RouteDoc[] = [
-  { method: 'get', path: '/webhooks', summary: 'List webhooks (secrets redacted)', tag: 'Webhooks', responseKey: 'webhooks' },
-  { method: 'post', path: '/webhooks', summary: 'Register a webhook; the signing secret is returned once', tag: 'Webhooks', body: schemas.CreateWebhookSchema, responseKey: 'webhook', status: 201 },
-  { method: 'get', path: '/webhooks/{webhookId}', summary: 'Get a webhook', tag: 'Webhooks', responseKey: 'webhook' },
-  { method: 'patch', path: '/webhooks/{webhookId}', summary: 'Update or rotate a webhook', tag: 'Webhooks', body: schemas.UpdateWebhookSchema, responseKey: 'webhook' },
-  { method: 'delete', path: '/webhooks/{webhookId}', summary: 'Delete a webhook', tag: 'Webhooks' },
-
-  { method: 'get', path: '/workflows', summary: 'List workflows', tag: 'Workflows', responseKey: 'workflows' },
-  { method: 'post', path: '/workflows', summary: 'Create a workflow', tag: 'Workflows', body: schemas.CreateWorkflowSchema, responseKey: 'workflow', status: 201 },
-  { method: 'get', path: '/workflows/{workflowId}', summary: 'Get a workflow', tag: 'Workflows', responseKey: 'workflow' },
-  { method: 'patch', path: '/workflows/{workflowId}', summary: 'Update a workflow', tag: 'Workflows', body: schemas.UpdateWorkflowSchema, responseKey: 'workflow' },
-  { method: 'delete', path: '/workflows/{workflowId}', summary: 'Delete a workflow', tag: 'Workflows' },
-
-  { method: 'get', path: '/projects', summary: 'List projects', tag: 'Projects', responseKey: 'projects' },
-  { method: 'post', path: '/projects', summary: 'Create a project', tag: 'Projects', body: schemas.CreateProjectSchema, responseKey: 'project', status: 201 },
-  { method: 'get', path: '/projects/{projectId}', summary: 'Get a project', tag: 'Projects', responseKey: 'project' },
-  { method: 'patch', path: '/projects/{projectId}', summary: 'Update a project', tag: 'Projects', body: schemas.UpdateProjectSchema, responseKey: 'project' },
-  { method: 'delete', path: '/projects/{projectId}', summary: 'Delete a project and its tasks', tag: 'Projects' },
-  { method: 'get', path: '/projects/{projectId}/critical-path', summary: 'Critical path (CPM) analysis', tag: 'Analysis', responseKey: 'analysis' },
-  { method: 'get', path: '/projects/{projectId}/ladder', summary: 'Timeline ladder of abstraction', tag: 'Analysis', query: ['level', 'containerId', 'iterationId'], responseKey: 'ladder' },
-  { method: 'get', path: '/projects/{projectId}/workload', summary: 'Project workload distribution', tag: 'Analysis', query: ['startDate', 'endDate', 'interval', 'groupBy', 'metric', 'defaultWeeklyCapacityHours'], responseKey: 'workload' },
-
-  { method: 'get', path: '/tasks', summary: 'List tasks (filtered, paginated oldest first; follow nextCursor)', tag: 'Tasks', query: ['projectId', 'status', 'priority', 'assigneeId', 'iterationId', 'deliverableId', 'containerId', 'parentId', 'limit', 'cursor'], responseKey: 'tasks' },
-  { method: 'post', path: '/tasks', summary: 'Create a task', tag: 'Tasks', body: schemas.CreateTaskSchema, responseKey: 'task', status: 201 },
-  { method: 'get', path: '/tasks/{taskId}', summary: 'Get a task', tag: 'Tasks', responseKey: 'task' },
-  { method: 'patch', path: '/tasks/{taskId}', summary: 'Update a task (enforces workflow transitions)', tag: 'Tasks', body: schemas.UpdateTaskSchema, responseKey: 'task' },
-  { method: 'delete', path: '/tasks/{taskId}', summary: 'Delete a task with its subtasks, dependencies, comments, attachments and time entries (subtasks=detach keeps subtasks)', tag: 'Tasks', query: ['subtasks'] },
-  { method: 'get', path: '/tasks/{taskId}/comments', summary: 'List task comments', tag: 'Comments', responseKey: 'comments' },
-  { method: 'post', path: '/tasks/{taskId}/comments', summary: 'Comment on a task', tag: 'Comments', body: schemas.CreateCommentSchema.omit({ taskId: true }), responseKey: 'comment', status: 201 },
-  { method: 'get', path: '/tasks/{taskId}/attachments', summary: 'List task attachments', tag: 'Attachments', responseKey: 'attachments' },
-  { method: 'post', path: '/tasks/{taskId}/attachments', summary: 'Attach a file link to a task', tag: 'Attachments', body: schemas.CreateAttachmentSchema.omit({ taskId: true }), responseKey: 'attachment', status: 201 },
-  { method: 'get', path: '/tasks/{taskId}/dependencies', summary: 'Task dependency graph', tag: 'Dependencies', responseKey: 'graph' },
-  { method: 'post', path: '/tasks/{taskId}/dependencies', summary: 'Add a dependency (409 on cycles)', tag: 'Dependencies', body: schemas.CreateDependencySchema, responseKey: 'dependency', status: 201 },
-  { method: 'delete', path: '/tasks/{taskId}/dependencies/{dependencyId}', summary: 'Remove a dependency', tag: 'Dependencies' },
-  { method: 'get', path: '/tasks/{taskId}/lifecycle', summary: 'Derived lifecycle state', tag: 'Tasks', responseKey: 'state' },
-  { method: 'get', path: '/tasks/{taskId}/transitions', summary: 'Allowed status transitions', tag: 'Tasks' },
-  { method: 'get', path: '/tasks/{taskId}/ladder', summary: 'Single-task ladder view', tag: 'Analysis', responseKey: 'taskLadder' },
-  { method: 'get', path: '/tasks/{taskId}/metrics', summary: 'Task metrics and EVM', tag: 'Analysis', responseKey: 'metrics' },
-  { method: 'get', path: '/tasks/{taskId}/progress-history', summary: 'Reconstructed progress history', tag: 'Analysis', responseKey: 'progressHistory' },
-
-  { method: 'get', path: '/teams', summary: 'List teams', tag: 'Teams', responseKey: 'teams' },
-  { method: 'post', path: '/teams', summary: 'Create a team', tag: 'Teams', body: schemas.CreateTeamSchema, responseKey: 'team', status: 201 },
-  { method: 'get', path: '/teams/{teamId}', summary: 'Get a team', tag: 'Teams', responseKey: 'team' },
-  { method: 'patch', path: '/teams/{teamId}', summary: 'Update a team', tag: 'Teams', body: schemas.UpdateTeamSchema, responseKey: 'team' },
-  { method: 'delete', path: '/teams/{teamId}', summary: 'Delete a team', tag: 'Teams' },
-
-  { method: 'get', path: '/containers', summary: 'List containers', tag: 'Containers', query: ['projectId!'], responseKey: 'containers' },
-  { method: 'post', path: '/containers', summary: 'Create a container', tag: 'Containers', body: schemas.CreateContainerSchema, responseKey: 'container', status: 201 },
-  { method: 'get', path: '/containers/{containerId}', summary: 'Get a container', tag: 'Containers', responseKey: 'container' },
-  { method: 'patch', path: '/containers/{containerId}', summary: 'Update a container', tag: 'Containers', body: schemas.UpdateContainerSchema, responseKey: 'container' },
-  { method: 'delete', path: '/containers/{containerId}', summary: 'Delete a container', tag: 'Containers' },
-
-  { method: 'get', path: '/deliverables', summary: 'List deliverables', tag: 'Deliverables', query: ['projectId!'], responseKey: 'deliverables' },
-  { method: 'post', path: '/deliverables', summary: 'Create a deliverable', tag: 'Deliverables', body: schemas.CreateDeliverableSchema, responseKey: 'deliverable', status: 201 },
-  { method: 'get', path: '/deliverables/{deliverableId}', summary: 'Get a deliverable', tag: 'Deliverables', responseKey: 'deliverable' },
-  { method: 'get', path: '/deliverables/{deliverableId}/summary', summary: 'Deliverable rollup summary', tag: 'Deliverables', responseKey: 'summary' },
-  { method: 'patch', path: '/deliverables/{deliverableId}', summary: 'Update a deliverable', tag: 'Deliverables', body: schemas.UpdateDeliverableSchema, responseKey: 'deliverable' },
-  { method: 'delete', path: '/deliverables/{deliverableId}', summary: 'Delete a deliverable', tag: 'Deliverables' },
-
-  { method: 'get', path: '/iterations', summary: 'List iterations', tag: 'Iterations', query: ['projectId!'], responseKey: 'iterations' },
-  { method: 'post', path: '/iterations', summary: 'Create an iteration', tag: 'Iterations', body: schemas.CreateIterationSchema, responseKey: 'iteration', status: 201 },
-  { method: 'get', path: '/iterations/{iterationId}', summary: 'Get an iteration', tag: 'Iterations', responseKey: 'iteration' },
-  { method: 'patch', path: '/iterations/{iterationId}', summary: 'Update an iteration', tag: 'Iterations', body: schemas.UpdateIterationSchema, responseKey: 'iteration' },
-  { method: 'delete', path: '/iterations/{iterationId}', summary: 'Delete an iteration', tag: 'Iterations' },
-
-  { method: 'get', path: '/activities', summary: 'Activity (audit) stream, newest first (follow nextCursor)', tag: 'Activity', query: ['projectId', 'taskId', 'limit', 'cursor'], responseKey: 'activities' },
-
-  { method: 'get', path: '/comments', summary: 'List comments for a task', tag: 'Comments', query: ['taskId!'], responseKey: 'comments' },
-  { method: 'post', path: '/comments', summary: 'Create a comment', tag: 'Comments', body: schemas.CreateCommentSchema, responseKey: 'comment', status: 201 },
-  { method: 'get', path: '/comments/{commentId}', summary: 'Get a comment', tag: 'Comments', responseKey: 'comment' },
-  { method: 'patch', path: '/comments/{commentId}', summary: 'Update a comment', tag: 'Comments', body: schemas.UpdateCommentSchema, responseKey: 'comment' },
-  { method: 'delete', path: '/comments/{commentId}', summary: 'Delete a comment', tag: 'Comments' },
-  { method: 'post', path: '/comments/{commentId}/reactions', summary: 'Add a reaction', tag: 'Comments', body: schemas.CommentReactionSchema, responseKey: 'comment' },
-  { method: 'delete', path: '/comments/{commentId}/reactions', summary: 'Remove a reaction', tag: 'Comments', query: ['emoji!'], responseKey: 'comment' },
-
-  { method: 'get', path: '/attachments', summary: 'List attachments', tag: 'Attachments', query: ['taskId', 'projectId', 'commentId'], responseKey: 'attachments' },
-  { method: 'post', path: '/attachments', summary: 'Register an attachment', tag: 'Attachments', body: schemas.CreateAttachmentSchema, responseKey: 'attachment', status: 201 },
-  { method: 'post', path: '/attachments/upload', summary: 'Upload a file through the configured FileStorageAdapter', tag: 'Attachments', body: schemas.UploadAttachmentSchema, responseKey: 'attachment', status: 201 },
-  { method: 'post', path: '/attachments/presign', summary: 'Request a presigned upload URL', tag: 'Attachments', body: schemas.PresignAttachmentSchema, responseKey: 'presigned' },
-  { method: 'get', path: '/attachments/{attachmentId}', summary: 'Get an attachment', tag: 'Attachments', responseKey: 'attachment' },
-  { method: 'delete', path: '/attachments/{attachmentId}', summary: 'Delete an attachment', tag: 'Attachments' },
-
-  { method: 'get', path: '/time-entries', summary: 'List time entries for a task', tag: 'Time Tracking', query: ['taskId!'], responseKey: 'timeEntries' },
-  { method: 'post', path: '/time-entries', summary: 'Log time against a task', tag: 'Time Tracking', body: schemas.LogTimeSchema, responseKey: 'timeEntry', status: 201 },
-
-  { method: 'get', path: '/workload', summary: 'Workload distribution across projects', tag: 'Analysis', query: ['projectId', 'startDate', 'endDate', 'interval', 'groupBy', 'metric', 'defaultWeeklyCapacityHours'], responseKey: 'workload' },
-  { method: 'post', path: '/status', summary: 'Publish an agent status update', tag: 'Agents' }
-];
-
-const errorResponse = {
-  description: 'Error',
-  content: {
-    'application/json': {
-      schema: {
-        type: 'object',
-        properties: {
-          error: { type: 'string' },
-          issues: { type: 'array', items: { type: 'object', properties: { path: { type: 'string' }, message: { type: 'string' } } } }
-        },
-        required: ['error']
-      }
-    }
-  }
-};
-
-function toJsonSchema(schema: unknown): Record<string, unknown> {
-  const { $schema: _ignored, ...json } = zodToJsonSchema(schema as any, { $refStrategy: 'none' }) as Record<string, unknown>;
-  return json;
-}
-
-export interface OpenApiOptions {
-  /** Public URL the API is served from, e.g. `https://app.example.com/api/critical-path`. */
-  serverUrl?: string;
-  title?: string;
-  version?: string;
-}
-
-/**
- * Builds an OpenAPI 3.1 document for the router. Request bodies are generated from the same zod
- * schemas the router validates with, so the contract cannot drift from enforcement.
- */
-export function buildOpenApiDocument(options: OpenApiOptions = {}): Record<string, unknown> {
-  const paths: Record<string, Record<string, unknown>> = {};
-
-  for (const route of ROUTES) {
-    const pathParams = [...route.path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
-    const parameters = [
-      ...pathParams.map((name) => ({ name, in: 'path', required: true, schema: { type: 'string' } })),
-      ...(route.query ?? []).map((q) => ({
-        name: q.replace(/!$/, ''),
-        in: 'query',
-        required: q.endsWith('!'),
-        schema: { type: 'string' }
-      }))
-    ];
-    const status = String(route.status ?? 200);
-    const successSchema = route.responseKey
-      ? { type: 'object', properties: { [route.responseKey]: {} }, required: [route.responseKey] }
-      : { type: 'object' };
-
-    paths[route.path] ??= {};
-    paths[route.path][route.method] = {
-      summary: route.summary,
-      tags: [route.tag],
-      ...(parameters.length ? { parameters } : {}),
-      ...(route.body
-        ? { requestBody: { required: true, content: { 'application/json': { schema: toJsonSchema(route.body) } } } }
-        : {}),
-      responses: {
-        [status]: { description: 'Success', content: { 'application/json': { schema: successSchema } } },
-        '400': errorResponse,
-        '401': errorResponse,
-        '403': errorResponse,
-        '404': errorResponse,
-        ...(route.path.endsWith('/dependencies') && route.method === 'post' ? { '409': errorResponse } : {}),
-        '500': errorResponse
-      }
-    };
-  }
-
-  return {
-    openapi: '3.1.0',
-    info: { title: options.title ?? 'Critical Path API', version: options.version ?? '1.0.0' },
-    ...(options.serverUrl ? { servers: [{ url: options.serverUrl }] } : {}),
-    paths
-  };
-}