@critical-path/core 0.27.0 → 0.28.0

package/src/plugins/plugins.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  CriticalPathEngine,
+  CustomFieldValidationError,
+  ValidationError,
+  WorkflowValidationError,
+  type CriticalPathPlugin
+} from '../index.js';
+
+const strictWorkflow = {
+  name: 'Strict',
+  defaultStatusKey: 'todo',
+  statuses: [
+    { key: 'todo', label: 'To Do', category: 'not_started' as const },
+    { key: 'doing', label: 'Doing', category: 'in_progress' as const },
+    { key: 'done', label: 'Done', category: 'completed' as const }
+  ],
+  transitions: [
+    { fromStatusKey: 'todo', toStatusKey: 'doing' },
+    { fromStatusKey: 'doing', toStatusKey: 'done' }
+  ]
+};
+
+describe('plugin system', () => {
+  it('runs init once with the engine before ready resolves', async () => {
+    const init = vi.fn(async (engine: CriticalPathEngine) => {
+      await engine.createProject({ name: 'Seeded by plugin' });
+    });
+    const engine = new CriticalPathEngine({ plugins: [{ id: 'seed', name: 'Seed', version: '1', init }] });
+    await engine.ready;
+
+    expect(init).toHaveBeenCalledTimes(1);
+    expect(init).toHaveBeenCalledWith(engine);
+    expect(await engine.getProjects()).toHaveLength(1);
+  });
+
+  it('surfaces init failures through ready without unhandled rejections', async () => {
+    const engine = new CriticalPathEngine({
+      plugins: [{ id: 'bad', name: 'Bad', version: '1', init: () => Promise.reject(new Error('boom')) }]
+    });
+    await expect(engine.ready).rejects.toThrow('boom');
+  });
+
+  it('validates values of plugin-registered custom field types and rejects unknown types', async () => {
+    const urlField: CriticalPathPlugin = {
+      id: 'url-field',
+      name: 'URL field',
+      version: '1',
+      customFieldTypes: [
+        { type: 'url', validate: (value) => (typeof value === 'string' && /^https?:\/\//.test(value) ? null : 'must be an http(s) URL') }
+      ]
+    };
+    const engine = new CriticalPathEngine({ plugins: [urlField] });
+    const project = await engine.createProject({
+      name: 'Links',
+      customFieldDefinitions: [{ id: 'f1', key: 'spec', label: 'Spec', type: 'url' }]
+    });
+
+    await engine.createTask({ projectId: project.id, title: 'ok', customFields: { spec: 'https://example.com' } });
+    await expect(engine.createTask({ projectId: project.id, title: 'bad', customFields: { spec: 'ftp://x' } })).rejects.toThrow(
+      /must be an http\(s\) URL/
+    );
+    await expect(
+      engine.createProject({ name: 'Unknown', customFieldDefinitions: [{ id: 'f', key: 'x', label: 'X', type: 'nope' }] })
+    ).rejects.toThrow(CustomFieldValidationError);
+  });
+
+  it('refuses custom field types that clash with built-in or already registered types', () => {
+    const clash = (type: string): CriticalPathPlugin => ({
+      id: `p-${type}-${Math.random()}`,
+      name: 'Clash',
+      version: '1',
+      customFieldTypes: [{ type, validate: () => null }]
+    });
+    expect(() => new CriticalPathEngine({ plugins: [clash('number')] })).toThrow(/already exists/);
+    expect(() => new CriticalPathEngine({ plugins: [clash('money'), clash('money')] })).toThrow(/already exists/);
+  });
+
+  it('validates the output of before-hooks, so plugins cannot bypass workflow rules', async () => {
+    const skipAhead: CriticalPathPlugin = {
+      id: 'skip',
+      name: 'Skip ahead',
+      version: '1',
+      hooks: { beforeTaskUpdate: (_id, updates) => ({ ...updates, status: 'done' }) }
+    };
+    const engine = new CriticalPathEngine({ plugins: [skipAhead] });
+    const workflow = await engine.createWorkflow(strictWorkflow);
+    const project = await engine.createProject({ name: 'Strict', workflowId: workflow.id });
+    const task = await engine.createTask({ projectId: project.id, title: 'T' });
+
+    await expect(engine.updateTask(task.id, { title: 'renamed' })).rejects.toThrow(WorkflowValidationError);
+    expect((await engine.getTask(task.id))?.status).toBe('todo');
+  });
+
+  it('prevents before-hooks from moving tasks between projects', async () => {
+    let otherProjectId = '';
+    const mover: CriticalPathPlugin = {
+      id: 'mover',
+      name: 'Mover',
+      version: '1',
+      hooks: {
+        beforeTaskCreate: (task) => (task.title === 'move me' ? { ...task, projectId: otherProjectId } : task),
+        beforeTaskUpdate: (_id, updates) => ({ ...updates, projectId: otherProjectId })
+      }
+    };
+    const engine = new CriticalPathEngine({ plugins: [mover] });
+    const home = await engine.createProject({ name: 'Home' });
+    otherProjectId = (await engine.createProject({ name: 'Other' })).id;
+
+    await expect(engine.createTask({ projectId: home.id, title: 'move me' })).rejects.toThrow(ValidationError);
+    const task = await engine.createTask({ projectId: home.id, title: 'stay' });
+    await engine.updateTask(task.id, { title: 'still here' });
+    expect((await engine.getTask(task.id))?.projectId).toBe(home.id);
+  });
+
+  it('enforces required custom fields even when none are supplied', async () => {
+    const engine = new CriticalPathEngine();
+    const project = await engine.createProject({
+      name: 'Required',
+      customFieldDefinitions: [{ id: 'f', key: 'client', label: 'Client', type: 'text', required: true }]
+    });
+    await expect(engine.createTask({ projectId: project.id, title: 'missing' })).rejects.toThrow(/required/);
+  });
+
+  it('logs after-hook failures without failing the write or skipping events', async () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const engine = new CriticalPathEngine({
+      plugins: [{ id: 'flaky', name: 'Flaky', version: '1', hooks: { afterTaskCreate: () => { throw new Error('downstream'); } } }]
+    });
+    const published: string[] = [];
+    engine.events.subscribe('task.created', (e) => void published.push(e.name));
+
+    const project = await engine.createProject({ name: 'After' });
+    const task = await engine.createTask({ projectId: project.id, title: 'stored' });
+    expect(await engine.getTask(task.id)).not.toBeNull();
+    expect(published).toEqual(['task.created']);
+    expect(consoleError).toHaveBeenCalledWith(expect.stringContaining('"flaky" afterTaskCreate'), expect.any(Error));
+    consoleError.mockRestore();
+  });
+
+  it('passes the deleted task to delete hooks', async () => {
+    const seen: string[] = [];
+    const engine = new CriticalPathEngine({
+      plugins: [
+        {
+          id: 'audit',
+          name: 'Audit',
+          version: '1',
+          hooks: {
+            beforeTaskDelete: (_id, task) => void seen.push(`before:${task.title}`),
+            afterTaskDelete: (_id, task) => void seen.push(`after:${task.title}`)
+          }
+        }
+      ]
+    });
+    const project = await engine.createProject({ name: 'Del' });
+    const task = await engine.createTask({ projectId: project.id, title: 'gone' });
+    await engine.deleteTask(task.id);
+    expect(seen).toEqual(['before:gone', 'after:gone']);
+  });
+});

package/src/schemas/index.ts

@@ -65,7 +65,8 @@ export const CustomFieldDefinitionSchema = strictObject({
   id: z.string(),
   key: nonEmpty,
   label: z.string(),
-  type: z.enum(['text', 'number', 'date', 'boolean', 'single_select', 'multi_select', 'user']),
+  /** Built-in type or one registered by a plugin (checked by the engine). */
+  type: nonEmpty,
   options: z.array(z.string()).optional(),
   required: z.boolean().optional(),
   defaultValue: z.unknown().optional()

package/src/types/index.ts

@@ -88,7 +88,8 @@ export interface CustomFieldDefinition {
   id: string;
   key: string;
   label: string;
-  type: 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'user';
+  /** A built-in type, or a type registered by a plugin's `customFieldTypes`. */
+  type: 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'user' | (string & {});
   options?: string[];
   required?: boolean;
   defaultValue?: unknown;
@@ -448,23 +449,74 @@ export type PublicWebhook = Omit<Webhook, 'secret'> & { hasSecret: boolean };
  */
 export type WebhookEvent = import('../domain/events.js').CriticalPathDomainEvent['name'] | '*';
 
+/**
+ * Lifecycle hooks, run in plugin registration order.
+ *
+ * - `before*` hooks may transform the input or throw to abort the operation. Their output is
+ *   validated (workflow transitions, custom fields) exactly like caller input, and they cannot
+ *   move a task to another project.
+ * - `after*` hooks run once the change is stored. Errors are logged and do not fail the call.
+ */
 export interface PluginHooks {
   beforeTaskCreate?: (task: Partial<Task>) => Promise<Partial<Task>> | Partial<Task>;
   afterTaskCreate?: (task: Task) => Promise<void> | void;
   beforeTaskUpdate?: (id: string, updates: Partial<Task>) => Promise<Partial<Task>> | Partial<Task>;
   afterTaskUpdate?: (task: Task, previousState: Task) => Promise<void> | void;
-  beforeTaskDelete?: (id: string) => Promise<void> | void;
-  afterTaskDelete?: (id: string) => Promise<void> | void;
+  beforeTaskDelete?: (id: string, task: Task) => Promise<void> | void;
+  afterTaskDelete?: (id: string, task: Task) => Promise<void> | void;
+}
+
+/** A custom field type contributed by a plugin, e.g. `url` or `currency`. */
+export interface CustomFieldType {
+  /** The `type` value used in `CustomFieldDefinition`s. Must not clash with a built-in type. */
+  type: string;
+  label?: string;
+  /** Returns an error message for an invalid value, or nothing when valid. Not called for empty values. */
+  validate: (value: unknown, definition: CustomFieldDefinition) => string | null | undefined | void;
+}
+
+/** Context passed to plugin routes and middleware. */
+export interface PluginRequestContext {
+  /** The engine as the calling actor (authorization and tenancy apply). */
+  engine: import('../engine/index.js').CriticalPathEngine;
+  /** The caller resolved by the router's `getContext`, if any. */
+  context?: Record<string, unknown> & { userId?: string };
+  url: URL;
+  /** Path parameters from the route pattern, e.g. `{ projectId: 'p1' }` for `/reports/:projectId`. */
+  params: Record<string, string>;
 }
 
+export interface PluginRoute {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Path below the router's base, with `:name` parameters, e.g. `/reports/:projectId`. */
+  path: string;
+  handler: (request: Request, ctx: PluginRequestContext) => Response | Promise<Response>;
+}
+
+/**
+ * Wraps every routed request (after authentication). Call `next()` to continue, or return a
+ * `Response` to short-circuit (e.g. rate limiting).
+ */
+export type PluginMiddleware = (
+  request: Request,
+  ctx: Omit<PluginRequestContext, 'params'>,
+  next: () => Promise<Response>
+) => Response | Promise<Response>;
+
 export interface CriticalPathPlugin {
   id: string;
   name: string;
   version: string;
   description?: string;
   hooks?: PluginHooks;
-  customFieldTypes?: CustomFieldDefinition[];
-  init?: (engine: unknown) => Promise<void> | void;
+  /** Additional custom field types projects can use in `customFieldDefinitions`. */
+  customFieldTypes?: CustomFieldType[];
+  /** Runs once when the engine starts; `engine.ready` resolves after every plugin's `init`. */
+  init?: (engine: import('../engine/index.js').CriticalPathEngine) => Promise<void> | void;
+  /** HTTP routes served by `@critical-path/server`, matched before built-in routes. */
+  routes?: PluginRoute[];
+  /** Middleware run by `@critical-path/server` around every routed request. */
+  middleware?: PluginMiddleware;
 }
 
 export interface CriticalPathConfig {

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/authorization.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/authorization.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/schemas/index.ts","./src/schemas/schemas.test.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts","./src/webhooks/dispatcher.ts","./src/webhooks/index.ts","./src/webhooks/signature.ts","./src/webhooks/webhooks.test.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/authorization.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/errors.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/actor.test.ts","./src/engine/authorization.test.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/plugins/plugins.test.ts","./src/schemas/index.ts","./src/schemas/schemas.test.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts","./src/webhooks/dispatcher.ts","./src/webhooks/index.ts","./src/webhooks/signature.ts","./src/webhooks/webhooks.test.ts"],"version":"5.9.3"}