@critical-path/core 0.28.0 → 0.30.0

package/src/schemas/index.ts

@@ -11,6 +11,7 @@
 import { z } from 'zod';
 import { ValidationError, type ValidationIssue } from '../domain/errors.js';
 import { DOMAIN_EVENT_NAMES } from '../domain/events.js';
+import { MAX_PAGE_SIZE } from '../store/query.js';
 
 /**
  * Parses `data` with `schema`, returning the cleaned value (unknown keys stripped, defaults
@@ -324,6 +325,35 @@ export const LogTimeSchema = strictObject({
   loggedAt: isoString.optional()
 });
 
+// --- List queries (URL search parameters) ---
+
+const csv = z
+  .string()
+  .transform((value) => value.split(',').map((part) => part.trim()).filter(Boolean));
+const pageLimit = z.coerce.number().int().min(1).max(MAX_PAGE_SIZE);
+
+/** `GET /tasks` query parameters. `status` and `priority` are comma-separated; `parentId=none` means top-level. */
+export const TaskListQuerySchema = strictObject({
+  projectId: nonEmpty.optional(),
+  status: csv.optional(),
+  priority: csv.optional(),
+  assigneeId: nonEmpty.optional(),
+  iterationId: nonEmpty.optional(),
+  deliverableId: nonEmpty.optional(),
+  containerId: nonEmpty.optional(),
+  parentId: nonEmpty.transform((value) => (value === 'none' ? null : value)).optional(),
+  limit: pageLimit.optional(),
+  cursor: nonEmpty.optional()
+});
+
+/** `GET /activities` query parameters. */
+export const ActivityListQuerySchema = strictObject({
+  projectId: nonEmpty.optional(),
+  taskId: nonEmpty.optional(),
+  limit: pageLimit.optional(),
+  cursor: nonEmpty.optional()
+});
+
 // --- Webhooks ---
 
 export const CreateWebhookSchema = strictObject({
@@ -367,5 +397,6 @@ export type UploadAttachmentBody = z.input<typeof UploadAttachmentSchema>;
 export type PresignAttachmentBody = z.input<typeof PresignAttachmentSchema>;
 export type LogTimeBody = z.input<typeof LogTimeSchema>;
 export type CreateWebhookBody = z.input<typeof CreateWebhookSchema>;
+export type TaskListQueryParams = z.input<typeof TaskListQuerySchema>;
 export type UpdateWebhookBody = z.input<typeof UpdateWebhookSchema>;
 

package/src/store/firebase.ts

@@ -1,4 +1,5 @@
 import type { StorageAdapter } from './index.js';
+import { matchesActivityQuery, matchesTaskQuery, paginate, type ActivityQuery, type Page, type TaskQuery } from './query.js';
 import type {
   Project,
   Task,
@@ -104,6 +105,10 @@ export interface FirebaseStoreConfig {
   db: FirestoreDBInterface;
 }
 
+/**
+ * Removes `undefined` values, which Firestore rejects. Update methods write the complete merged
+ * record without `{ merge: true }`, so a field cleared with `undefined` is actually removed.
+ */
 export function sanitizeFirestoreData<T>(obj: T): T {
   if (obj === null || typeof obj !== 'object') {
     return obj;
@@ -162,7 +167,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('projects').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('projects').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -202,7 +207,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('workflows').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('workflows').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -238,7 +243,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: Team = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('teams').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('teams').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -274,7 +279,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: TaskContainer = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('containers').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('containers').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -318,7 +323,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!existing) return null;
 
     const updated: Deliverable = { ...existing, ...updates, updatedAt: new Date().toISOString() };
-    await this.db.collection('deliverables').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('deliverables').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -340,6 +345,12 @@ export class FirebaseStore implements StorageAdapter {
     return snap.docs.map((doc) => ({ ...doc.data(), id: doc.id }));
   }
 
+  /** Pushes down the project filter; remaining filters and pagination are applied in memory. */
+  async queryTasks(query: TaskQuery): Promise<Page<Task>> {
+    const tasks = (await this.getTasks(query.projectId)).filter((t) => matchesTaskQuery(t, query));
+    return paginate(tasks, (t) => t.createdAt, 'asc', query.limit, query.cursor);
+  }
+
   async getTask(id: string): Promise<Task | null> {
     const snap = await this.db.collection('tasks').doc(id).get();
     if (!snap.exists) return null;
@@ -363,7 +374,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('tasks').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('tasks').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -399,7 +410,7 @@ export class FirebaseStore implements StorageAdapter {
     if (!snap.exists) return null;
 
     const updated: Iteration = { ...snap.data(), id, ...updates };
-    await this.db.collection('iterations').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('iterations').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -439,7 +450,7 @@ export class FirebaseStore implements StorageAdapter {
       ...updates,
       updatedAt: new Date().toISOString()
     };
-    await this.db.collection('comments').doc(id).set(sanitizeFirestoreData(updated), { merge: true });
+    await this.db.collection('comments').doc(id).set(sanitizeFirestoreData(updated));
     return updated;
   }
 
@@ -522,6 +533,13 @@ export class FirebaseStore implements StorageAdapter {
     return snap.docs.map((doc) => ({ ...doc.data(), id: doc.id }));
   }
 
+  async queryActivities(query: ActivityQuery): Promise<Page<Activity>> {
+    const activities = (await this.getActivities({ projectId: query.projectId, taskId: query.taskId })).filter((a) =>
+      matchesActivityQuery(a, query)
+    );
+    return paginate(activities, (a) => a.createdAt, 'desc', query.limit, query.cursor);
+  }
+
   async logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity> {
     const docRef = this.db.collection('activities').doc();
     const now = new Date().toISOString();
@@ -567,6 +585,27 @@ export class FirebaseStore implements StorageAdapter {
     return newDep;
   }
 
+  async getDependency(id: string): Promise<TaskDependency | null> {
+    const doc = await this.db.collection('dependencies').doc(id).get();
+    return doc.exists ? ({ ...doc.data(), id: doc.id } as TaskDependency) : null;
+  }
+
+  async removeDependency(id: string): Promise<boolean> {
+    return this.deleteDoc('dependencies', id);
+  }
+
+  async deleteTimeEntry(id: string): Promise<boolean> {
+    return this.deleteDoc('time_entries', id);
+  }
+
+  private async deleteDoc(collection: string, id: string): Promise<boolean> {
+    const ref = this.db.collection(collection).doc(id);
+    const doc = await ref.get();
+    if (!doc.exists) return false;
+    await ref.delete();
+    return true;
+  }
+
   // --- Webhooks ---
   async getWebhooks(): Promise<Webhook[]> {
     const snap = await this.db.collection('webhooks').get();

package/src/store/index.ts

@@ -18,6 +18,16 @@ import type {
   CreateDeliverableInput
 } from '../types/index.js';
 import { generateProjectKey } from '../utils/key.js';
+import {
+  matchesActivityQuery,
+  matchesTaskQuery,
+  paginate,
+  type ActivityQuery,
+  type Page,
+  type TaskQuery
+} from './query.js';
+
+export * from './query.js';
 
 export interface ProjectRepository {
   getProjects(): Promise<Project[]>;
@@ -37,6 +47,8 @@ export interface WorkflowRepository {
 
 export interface TaskRepository {
   getTasks(projectId?: string): Promise<Task[]>;
+  /** Filtered, paginated tasks ordered by `(createdAt, id)` ascending. */
+  queryTasks(query: TaskQuery): Promise<Page<Task>>;
   getTask(id: string): Promise<Task | null>;
   createTask(task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>): Promise<Task>;
   updateTask(id: string, updates: Partial<Task>): Promise<Task | null>;
@@ -86,17 +98,23 @@ export interface AttachmentRepository {
 
 export interface ActivityRepository {
   getActivities(filter?: { projectId?: string; taskId?: string }): Promise<Activity[]>;
+  /** Paginated activity feed ordered by `(createdAt, id)` descending (newest first). */
+  queryActivities(query: ActivityQuery): Promise<Page<Activity>>;
   logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity>;
 }
 
 export interface TimeEntryRepository {
   getTimeEntries(taskId: string): Promise<TimeEntry[]>;
   logTime(entry: Omit<TimeEntry, 'id' | 'loggedAt'> & { loggedAt?: string }): Promise<TimeEntry>;
+  deleteTimeEntry(id: string): Promise<boolean>;
 }
 
 export interface DependencyRepository {
+  /** Dependencies where `taskId` is either the dependent or the upstream task. */
   getDependencies(taskId: string): Promise<TaskDependency[]>;
+  getDependency(id: string): Promise<TaskDependency | null>;
   addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency>;
+  removeDependency(id: string): Promise<boolean>;
 }
 
 export interface WebhookRepository {
@@ -230,6 +248,11 @@ export class InMemoryStore implements StorageAdapter {
     return all;
   }
 
+  async queryTasks(query: TaskQuery): Promise<Page<Task>> {
+    const tasks = Array.from(this.tasks.values()).filter((t) => matchesTaskQuery(t, query));
+    return paginate(tasks, (t) => t.createdAt, 'asc', query.limit, query.cursor);
+  }
+
   async getTask(id: string): Promise<Task | null> {
     return this.tasks.get(id) || null;
   }
@@ -503,6 +526,11 @@ export class InMemoryStore implements StorageAdapter {
     });
   }
 
+  async queryActivities(query: ActivityQuery): Promise<Page<Activity>> {
+    const activities = this.activities.filter((a) => matchesActivityQuery(a, query));
+    return paginate(activities, (a) => a.createdAt, 'desc', query.limit, query.cursor);
+  }
+
   async logActivity(activity: Omit<Activity, 'id' | 'createdAt'>): Promise<Activity> {
     const id = `act_${Math.random().toString(36).substring(2, 9)}`;
     const newAct: Activity = { ...activity, id, createdAt: new Date().toISOString() };
@@ -522,6 +550,10 @@ export class InMemoryStore implements StorageAdapter {
     return newEntry;
   }
 
+  async deleteTimeEntry(id: string): Promise<boolean> {
+    return this.timeEntries.delete(id);
+  }
+
   // Dependencies
   async getDependencies(taskId: string): Promise<TaskDependency[]> {
     return Array.from(this.dependencies.values()).filter(
@@ -529,6 +561,10 @@ export class InMemoryStore implements StorageAdapter {
     );
   }
 
+  async getDependency(id: string): Promise<TaskDependency | null> {
+    return this.dependencies.get(id) ?? null;
+  }
+
   async addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency> {
     const id = `dep_${Math.random().toString(36).substring(2, 9)}`;
     const newDep: TaskDependency = { ...dep, id };
@@ -536,6 +572,10 @@ export class InMemoryStore implements StorageAdapter {
     return newDep;
   }
 
+  async removeDependency(id: string): Promise<boolean> {
+    return this.dependencies.delete(id);
+  }
+
   // Webhooks
   async getWebhooks(): Promise<Webhook[]> {
     return Array.from(this.webhooks.values());

package/src/store/query.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import {
+  CriticalPathEngine,
+  InMemoryStore,
+  SQLiteStore,
+  FirebaseStore,
+  InMemoryFirestoreMock,
+  ValidationError,
+  createRolePolicy,
+  MAX_PAGE_SIZE,
+  type StorageAdapter,
+  type Task
+} from '../index.js';
+
+const stores: Array<[string, () => StorageAdapter]> = [
+  ['InMemoryStore', () => new InMemoryStore()],
+  ['SQLiteStore', () => new SQLiteStore({ filename: ':memory:' })],
+  ['FirebaseStore', () => new FirebaseStore({ db: new InMemoryFirestoreMock() })]
+];
+
+describe.each(stores)('task and activity queries (%s)', (_name, makeStore) => {
+  async function setup() {
+    const engine = new CriticalPathEngine({ store: makeStore() });
+    const project = await engine.createProject({ name: 'Query' });
+    const other = await engine.createProject({ name: 'Other' });
+    const sprint = await engine.createIteration({ projectId: project.id, name: 'S1', status: 'active' });
+    const parent = await engine.createTask({ projectId: project.id, title: 'Parent', status: 'in_progress', priority: 'high', assigneeId: 'ana' });
+    const child = await engine.createTask({ projectId: project.id, title: 'Child', parentId: parent.id, status: 'todo', priority: 'low', iterationId: sprint.id });
+    const shared = await engine.createTask({
+      projectId: project.id,
+      title: 'Shared',
+      status: 'done',
+      priority: 'high',
+      assignees: [{ id: 'ana', type: 'user' }, { id: 'ben', type: 'user' }]
+    });
+    const elsewhere = await engine.createTask({ projectId: other.id, title: 'Elsewhere', assigneeId: 'ana' });
+    return { engine, project, other, sprint, parent, child, shared, elsewhere };
+  }
+  const titles = (tasks: Task[]) => tasks.map((t) => t.title).sort();
+
+  it('filters by status, priority, assignee (including assignees), iteration and parent', async () => {
+    const { engine, project, sprint, parent } = await setup();
+    const q = (query: object) => engine.queryTasks({ projectId: project.id, ...query }).then((p) => titles(p.items));
+
+    expect(await q({ status: ['todo', 'done'] })).toEqual(['Child', 'Shared']);
+    expect(await q({ priority: ['high'] })).toEqual(['Parent', 'Shared']);
+    expect(await q({ assigneeId: 'ana' })).toEqual(['Parent', 'Shared']);
+    expect(await q({ assigneeId: 'ben' })).toEqual(['Shared']);
+    expect(await q({ iterationId: sprint.id })).toEqual(['Child']);
+    expect(await q({ parentId: parent.id })).toEqual(['Child']);
+    expect(await q({ parentId: null })).toEqual(['Parent', 'Shared']);
+    expect(titles((await engine.queryTasks({ assigneeId: 'ana' })).items)).toEqual(['Elsewhere', 'Parent', 'Shared']);
+  });
+
+  it('pages through every task exactly once, oldest first', async () => {
+    const { engine, project } = await setup();
+    for (let i = 0; i < 12; i++) await engine.createTask({ projectId: project.id, title: `Bulk ${i}` });
+
+    const seen: Task[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await engine.queryTasks({ projectId: project.id, limit: 5, cursor });
+      expect(page.items.length).toBeLessThanOrEqual(5);
+      seen.push(...page.items);
+      cursor = page.nextCursor;
+    } while (cursor);
+
+    expect(seen).toHaveLength(15);
+    expect(new Set(seen.map((t) => t.id)).size).toBe(15);
+    const keys = seen.map((t) => `${t.createdAt}|${t.id}`);
+    expect([...keys].sort()).toEqual(keys);
+  });
+
+  it('pages the activity feed newest first', async () => {
+    const { engine, project } = await setup();
+    const all = (await engine.queryActivities({ projectId: project.id, limit: MAX_PAGE_SIZE })).items;
+    expect(all.length).toBeGreaterThan(3);
+    const keys = all.map((a) => `${a.createdAt}|${a.id}`);
+    expect([...keys].sort().reverse()).toEqual(keys);
+
+    const first = await engine.queryActivities({ projectId: project.id, limit: 2 });
+    const second = await engine.queryActivities({ projectId: project.id, limit: 2, cursor: first.nextCursor });
+    expect([...first.items, ...second.items].map((a) => a.id)).toEqual(all.slice(0, 4).map((a) => a.id));
+  });
+
+  it('rejects malformed cursors and clamps page sizes', async () => {
+    const { engine, project } = await setup();
+    await expect(engine.queryTasks({ projectId: project.id, cursor: 'not-a-cursor' })).rejects.toThrow(ValidationError);
+    expect((await engine.queryTasks({ projectId: project.id, limit: 0 })).items).toHaveLength(1);
+    expect((await engine.queryTasks({ projectId: project.id, limit: 10_000 })).items).toHaveLength(3);
+  });
+});
+
+describe('query authorization', () => {
+  it('limits cross-project queries and activity feeds to readable projects', async () => {
+    const engine = new CriticalPathEngine({ authorize: createRolePolicy() });
+    const mine = await engine.createProject({ name: 'Mine', members: [{ userId: 'ana', role: 'viewer' }] });
+    const secret = await engine.createProject({ name: 'Secret' });
+    await engine.createTask({ projectId: mine.id, title: 'Visible' });
+    await engine.createTask({ projectId: secret.id, title: 'Hidden' });
+    const ana = engine.withActor({ userId: 'ana' });
+
+    expect((await ana.queryTasks()).items.map((t) => t.title)).toEqual(['Visible']);
+    expect((await ana.queryTasks({ projectId: secret.id })).items).toEqual([]);
+    expect((await ana.queryTasks({ projectIds: [mine.id, secret.id] })).items.map((t) => t.title)).toEqual(['Visible']);
+    const feed = (await ana.queryActivities()).items;
+    expect(feed.length).toBeGreaterThan(0);
+    expect(feed.every((a) => a.projectId === mine.id)).toBe(true);
+  });
+});

package/src/store/query.ts

@@ -0,0 +1,113 @@
+import type { Activity, Task } from '../types/index.js';
+import { ValidationError } from '../domain/errors.js';
+
+export const DEFAULT_PAGE_SIZE = 100;
+export const MAX_PAGE_SIZE = 500;
+
+/** Filters for `queryTasks`. All given filters must match. */
+export interface TaskQuery {
+  projectId?: string;
+  /** Restrict to these projects (used for authorization when no `projectId` is given). */
+  projectIds?: string[];
+  /** Any of these statuses. */
+  status?: string[];
+  /** Matches `assigneeId` or any entry in `assignees`. */
+  assigneeId?: string;
+  /** Any of these priorities. */
+  priority?: string[];
+  iterationId?: string;
+  deliverableId?: string;
+  containerId?: string;
+  /** A task id for its subtasks, or `null` for top-level tasks only. */
+  parentId?: string | null;
+  limit?: number;
+  /** Opaque cursor from a previous page's `nextCursor`. */
+  cursor?: string;
+}
+
+export interface ActivityQuery {
+  projectId?: string;
+  projectIds?: string[];
+  taskId?: string;
+  limit?: number;
+  cursor?: string;
+}
+
+/** One page of results. `nextCursor` is set when more results exist. */
+export interface Page<T> {
+  items: T[];
+  nextCursor?: string;
+}
+
+/** Clamps a requested page size to `[1, MAX_PAGE_SIZE]`, defaulting to `DEFAULT_PAGE_SIZE`. */
+export function pageSize(limit: number | undefined): number {
+  if (limit === undefined || !Number.isFinite(limit)) return DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(1, Math.floor(limit)), MAX_PAGE_SIZE);
+}
+
+/** Cursors encode the last item's sort key and id (keyset pagination). */
+export function encodeCursor(sortKey: string, id: string): string {
+  return btoa(JSON.stringify([sortKey, id])).replace(/=+$/, '');
+}
+
+export function decodeCursor(cursor: string | undefined): [string, string] | undefined {
+  if (!cursor) return undefined;
+  try {
+    const value = JSON.parse(atob(cursor));
+    if (Array.isArray(value) && value.length === 2 && value.every((v) => typeof v === 'string')) {
+      return value as [string, string];
+    }
+  } catch {
+    // fall through
+  }
+  throw new ValidationError('Invalid pagination cursor.');
+}
+
+export function matchesTaskQuery(task: Task, query: TaskQuery): boolean {
+  if (query.projectId && task.projectId !== query.projectId) return false;
+  if (query.projectIds && !query.projectIds.includes(task.projectId)) return false;
+  if (query.status?.length && !query.status.includes(task.status)) return false;
+  if (query.priority?.length && !query.priority.includes(task.priority)) return false;
+  if (query.iterationId && task.iterationId !== query.iterationId) return false;
+  if (query.deliverableId && task.deliverableId !== query.deliverableId) return false;
+  if (query.containerId && task.containerId !== query.containerId) return false;
+  if (query.parentId === null && task.parentId) return false;
+  if (query.parentId && task.parentId !== query.parentId) return false;
+  if (query.assigneeId && task.assigneeId !== query.assigneeId && !task.assignees?.some((a) => a.id === query.assigneeId)) {
+    return false;
+  }
+  return true;
+}
+
+export function matchesActivityQuery(activity: Activity, query: ActivityQuery): boolean {
+  if (query.projectId && activity.projectId !== query.projectId) return false;
+  if (query.projectIds && (!activity.projectId || !query.projectIds.includes(activity.projectId))) return false;
+  if (query.taskId && activity.taskId !== query.taskId) return false;
+  return true;
+}
+
+/**
+ * Sorts by `(sortKey, id)` and returns the page after `cursor`. Tasks page oldest first
+ * (`asc`), activity feeds newest first (`desc`).
+ */
+export function paginate<T extends { id: string }>(
+  items: T[],
+  sortKey: (item: T) => string,
+  direction: 'asc' | 'desc',
+  limit: number | undefined,
+  cursor: string | undefined
+): Page<T> {
+  const sign = direction === 'asc' ? 1 : -1;
+  const compare = (a: [string, string], b: [string, string]) =>
+    sign * (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0);
+  const after = decodeCursor(cursor);
+  const sorted = [...items].sort((a, b) => compare([sortKey(a), a.id], [sortKey(b), b.id]));
+  const remaining = after ? sorted.filter((item) => compare([sortKey(item), item.id], after) > 0) : sorted;
+  const size = pageSize(limit);
+  const page = remaining.slice(0, size);
+  const last = page[page.length - 1];
+  return {
+    items: page,
+    nextCursor: remaining.length > size && last ? encodeCursor(sortKey(last), last.id) : undefined
+  };
+}