@taskforcehq/taskforce 0.3.170 → 0.3.301

package/dist/sync/syncService.test.js

@@ -9,8 +9,38 @@ vi.mock('./cloudSyncApi', () => ({
     pullUserSettings: vi.fn(),
     pushUserSettings: vi.fn()
 }));
-import { pullWorkspaceChanges, pushWorkspaceChanges, applyLocalWorkspaceChanges, handshakeWorkspace, pullUserSettings, pushUserSettings } from './cloudSyncApi';
+import { pullWorkspaceChanges, pushWorkspaceChanges, applyLocalWorkspaceChanges, handshakeWorkspace, provisionWorkspace, pullUserSettings, pushUserSettings } from './cloudSyncApi';
 const mockResolveCloudAuthUrl = (p) => p;
+function buildPayload(overrides = {}) {
+    return {
+        changes: [],
+        currentTaskIds: new Set(),
+        deleteTaskIds: new Set(),
+        currentInitiativeIds: new Set(),
+        currentInitiativeWatermarks: new Map(),
+        currentWorkstreamIds: new Set(),
+        currentWorkstreamWatermarks: new Map(),
+        currentAiProfileIds: new Set(),
+        currentAiProfileWatermarks: new Map(),
+        currentDocumentPaths: new Set(),
+        deleteDocumentPaths: new Set(),
+        currentDocumentWatermarks: new Map(),
+        currentAssetPaths: new Set(),
+        deleteAssetPaths: new Set(),
+        currentAssetWatermarks: new Map(),
+        currentDocumentReviewSessionIds: new Set(),
+        deleteDocumentReviewSessionIds: new Set(),
+        currentDocumentReviewSessionWatermarks: new Map(),
+        currentDocumentReviewCommentIds: new Set(),
+        deleteDocumentReviewCommentIds: new Set(),
+        currentDocumentReviewCommentWatermarks: new Map(),
+        currentAnnotatedAttachmentSessionIds: new Set(),
+        deleteAnnotatedAttachmentSessionIds: new Set(),
+        currentAnnotatedAttachmentSessionWatermarks: new Map(),
+        pushedWatermarks: new Map(),
+        ...overrides
+    };
+}
 const baseHandshakeInput = {
     cloudAuthConfigured: true,
     runtimeMode: 'local',
@@ -33,15 +63,14 @@ describe('syncService', () => {
             const result = await runWorkspacePushSyncService({
                 resolveCloudAuthUrl: mockResolveCloudAuthUrl,
                 workspaceId: 'ws-1',
-                payload: {
+                payload: buildPayload({
                     changes: [{ op: 'document-delete', path: 'docs/remove.md' }],
                     currentTaskIds: new Set(['task-1']),
-                    deleteTaskIds: new Set(),
                     currentDocumentPaths: new Set(['docs/keep.md']),
                     deleteDocumentPaths: new Set(['docs/remove.md']),
                     currentDocumentWatermarks: new Map([['docs/keep.md', '2026-02-01T00:00:00.000Z']]),
                     pushedWatermarks: new Map([['task-1', 'wm-1']])
-                },
+                }),
                 ensureCloudWorkspaceReadyForSync: async () => ({ success: true })
             });
             expect(result.success).toBe(true);
@@ -51,15 +80,10 @@ describe('syncService', () => {
             expect(result.emittedEventIds).toEqual(['epoch-1:1', 'epoch-1:2']);
         });
         it('uses deterministic fallback idempotency key when crypto.subtle is unavailable', async () => {
-            const payload = {
+            const payload = buildPayload({
                 changes: [{ op: 'document-delete', path: 'docs/remove.md' }],
-                currentTaskIds: new Set(),
-                deleteTaskIds: new Set(),
-                currentDocumentPaths: new Set(),
                 deleteDocumentPaths: new Set(['docs/remove.md']),
-                currentDocumentWatermarks: new Map(),
-                pushedWatermarks: new Map()
-            };
+            });
             vi.mocked(pushWorkspaceChanges)
                 .mockResolvedValue({
                 ok: true,
@@ -106,15 +130,10 @@ describe('syncService', () => {
             const result = await runWorkspacePushSyncService({
                 resolveCloudAuthUrl: mockResolveCloudAuthUrl,
                 workspaceId: 'ws-retry',
-                payload: {
+                payload: buildPayload({
                     changes: [{ op: 'delete', taskId: 'task-1' }],
-                    currentTaskIds: new Set(),
                     deleteTaskIds: new Set(['task-1']),
-                    currentDocumentPaths: new Set(),
-                    deleteDocumentPaths: new Set(),
-                    currentDocumentWatermarks: new Map(),
-                    pushedWatermarks: new Map()
-                },
+                }),
                 ensureCloudWorkspaceReadyForSync
             });
             expect(result.success).toBe(true);
@@ -136,15 +155,10 @@ describe('syncService', () => {
             const result = await runWorkspacePushSyncService({
                 resolveCloudAuthUrl: mockResolveCloudAuthUrl,
                 workspaceId: 'ws-error',
-                payload: {
+                payload: buildPayload({
                     changes: [{ op: 'delete', taskId: 'task-1' }],
-                    currentTaskIds: new Set(),
                     deleteTaskIds: new Set(['task-1']),
-                    currentDocumentPaths: new Set(),
-                    deleteDocumentPaths: new Set(),
-                    currentDocumentWatermarks: new Map(),
-                    pushedWatermarks: new Map()
-                },
+                }),
                 ensureCloudWorkspaceReadyForSync: async () => ({ success: false })
             });
             expect(result.success).toBe(false);
@@ -209,6 +223,97 @@ describe('syncService', () => {
             expect(res.cursor).toBeNull();
             expect(res.success).toBe(true);
         });
+        it('forwards workspace members from pull into local apply', async () => {
+            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    workspaceMembers: [
+                        {
+                            userId: 'user-1',
+                            workspaceId: 'ws-1',
+                            email: 'member@example.com',
+                            displayName: 'Member One',
+                            role: 'member',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }
+                    ],
+                    changes: [{ op: 'upsert', task: { id: 't-1', title: 'Task', assignee: 'user-1' }, archived: false }],
+                    nextCursor: null,
+                    hasMore: false
+                }
+            });
+            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                failures: [],
+                data: { success: true }
+            });
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-1',
+                cursor: null,
+                bootstrap: false
+            });
+            expect(res.success).toBe(true);
+            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-1', expect.any(Array), expect.objectContaining({
+                workspaceMembers: [
+                    expect.objectContaining({
+                        userId: 'user-1',
+                        email: 'member@example.com'
+                    })
+                ]
+            }));
+        });
+        it('applies members-only pull pages even when no entity changes are returned', async () => {
+            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    workspaceMembers: [
+                        {
+                            userId: 'user-1',
+                            workspaceId: 'ws-1',
+                            email: 'member@example.com',
+                            displayName: 'Member One',
+                            role: 'member',
+                            permissionMode: 'read-write',
+                            betaAccess: true,
+                            status: 'active',
+                            disabled: false
+                        }
+                    ],
+                    changes: [],
+                    nextCursor: null,
+                    hasMore: false
+                }
+            });
+            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                failures: [],
+                data: { success: true }
+            });
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-1',
+                cursor: null,
+                bootstrap: false
+            });
+            expect(res.success).toBe(true);
+            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-1', [], expect.objectContaining({
+                workspaceMembers: [
+                    expect.objectContaining({
+                        userId: 'user-1'
+                    })
+                ]
+            }));
+        });
         it('surfaces retryAfterMs when cloud returns 429', async () => {
             vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
                 ok: false,
@@ -227,6 +332,19 @@ describe('syncService', () => {
             expect(res.status).toBe(429);
             expect(res.retryAfterMs).toBe(30_000);
         });
+        it('surfaces thrown pull exceptions as exception errors', async () => {
+            vi.mocked(pullWorkspaceChanges).mockRejectedValueOnce(new Error('duplicate key value violates unique constraint'));
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-1',
+                cursor: null,
+                bootstrap: false
+            });
+            expect(res.success).toBe(false);
+            expect(res.kind).toBe('exception');
+            expect(res.status).toBe(0);
+            expect(res.error).toContain('duplicate key value violates unique constraint');
+        });
         it('retries pull once after 403 when ensure succeeds', async () => {
             const ensureCloudWorkspaceReadyForSync = vi.fn().mockResolvedValue({ success: true });
             vi.mocked(pullWorkspaceChanges)
@@ -318,6 +436,34 @@ describe('syncService', () => {
             expect(res.kind).toBe('apply_auth');
             expect(res.status).toBe(401);
         });
+        it('surfaces apply-local error details from non-ok local apply responses', async () => {
+            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    changes: [{ op: 'upsert', task: { id: 't-parent', title: 'Parent', status: 'done', updatedAt: '2026-03-15T20:27:08.000Z' } }],
+                    nextCursor: null,
+                    hasMore: false
+                }
+            });
+            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
+                ok: false,
+                status: 400,
+                failures: ['/api/taskforce/sync/workspace/apply-local:400'],
+                data: { error: 'Parent tasks cannot be marked done manually; completion is derived from descendants' }
+            });
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-1',
+                cursor: null,
+                bootstrap: false
+            });
+            expect(res.success).toBe(false);
+            expect(res.kind).toBe('apply_all_candidates');
+            expect(res.status).toBe(400);
+            expect(res.error).toBe('Parent tasks cannot be marked done manually; completion is derived from descendants');
+        });
         it('surfaces document decryption failures without failing pull', async () => {
             const previousKey = process.env.TASKFORCE_SYNC_KEY;
             process.env.TASKFORCE_SYNC_KEY = 'test-sync-key';
@@ -354,6 +500,97 @@ describe('syncService', () => {
                     delete process.env.TASKFORCE_SYNC_KEY;
             }
         });
+        it('zero-change bootstrap pull (no changes, hasMore false) returns success true', async () => {
+            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    changes: [],
+                    nextCursor: null,
+                    hasMore: false
+                }
+            });
+            vi.mocked(applyLocalWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: { success: true },
+                failures: []
+            });
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-bootstrap',
+                cursor: null,
+                bootstrap: true
+            });
+            expect(res.success).toBe(true);
+            expect(res.appliedChanges).toBe(0);
+            expect(res.cursor).toBeNull();
+            expect(applyLocalWorkspaceChanges).toHaveBeenCalledWith('ws-bootstrap', [], {
+                bootstrapSnapshot: {
+                    currentAnnotatedAttachmentSessionIds: []
+                }
+            });
+        });
+        it('sends pulled annotated attachment session ids during bootstrap reconciliation', async () => {
+            vi.mocked(pullWorkspaceChanges).mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: {
+                    success: true,
+                    changes: [{
+                            op: 'annotated-attachment-session-upsert',
+                            session: {
+                                id: 'session-1',
+                                workspaceId: 'ws-annotated',
+                                taskId: 'task-1',
+                                baseImageAssetId: 'asset-1',
+                                title: 'Session 1',
+                                globalInstruction: null,
+                                annotations: [],
+                                createdByActorId: null,
+                                updatedByActorId: null,
+                                createdAt: '2026-03-26T00:00:00.000Z',
+                                updatedAt: '2026-03-26T00:00:00.000Z',
+                                deletedAt: null
+                            }
+                        }],
+                    nextCursor: null,
+                    hasMore: false
+                }
+            });
+            vi.mocked(applyLocalWorkspaceChanges)
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: { success: true },
+                failures: []
+            })
+                .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                data: { success: true },
+                failures: []
+            });
+            const res = await runWorkspacePullSyncService({
+                resolveCloudAuthUrl: mockResolveCloudAuthUrl,
+                workspaceId: 'ws-annotated',
+                cursor: null,
+                bootstrap: true
+            });
+            expect(res.success).toBe(true);
+            expect(applyLocalWorkspaceChanges).toHaveBeenNthCalledWith(1, 'ws-annotated', expect.arrayContaining([
+                expect.objectContaining({
+                    op: 'annotated-attachment-session-upsert',
+                    session: expect.objectContaining({ id: 'session-1' })
+                })
+            ]), expect.objectContaining({ repairMode: false }));
+            expect(applyLocalWorkspaceChanges).toHaveBeenNthCalledWith(2, 'ws-annotated', [], {
+                bootstrapSnapshot: {
+                    currentAnnotatedAttachmentSessionIds: ['session-1']
+                }
+            });
+        });
         it('stops at maxPages and returns partial success', async () => {
             // Always returns hasMore=true so the loop would run forever without maxPages
             vi.mocked(pullWorkspaceChanges).mockResolvedValue({
@@ -380,6 +617,7 @@ describe('syncService', () => {
     describe('ensureCloudWorkspaceReadyForSyncService', () => {
         beforeEach(() => {
             vi.mocked(handshakeWorkspace).mockReset();
+            vi.mocked(provisionWorkspace).mockReset();
         });
         it('returns success when handshake succeeds', async () => {
             vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
@@ -407,6 +645,15 @@ describe('syncService', () => {
             expect(res.statusCode).toBe(429);
             expect(res.retryAfterMs).toBe(45_000);
         });
+        it('marks status 0 handshake failures as transient', async () => {
+            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
+                ok: false, status: 0, data: {}
+            });
+            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
+            expect(res.success).toBe(false);
+            expect(res.statusCode).toBe(0);
+            expect(res.transient).toBe(true);
+        });
         it('returns failure when cloudAuthConfigured is false', async () => {
             const res = await ensureCloudWorkspaceReadyForSyncService({
                 ...baseHandshakeInput,
@@ -431,6 +678,23 @@ describe('syncService', () => {
             expect(res.success).toBe(false);
             expect(handshakeWorkspace).not.toHaveBeenCalled();
         });
+        it('maps workspace access conflicts to user-facing guidance', async () => {
+            vi.mocked(handshakeWorkspace).mockResolvedValueOnce({
+                ok: false,
+                status: 409,
+                data: { code: 'WORKSPACE_ID_MISMATCH', error: 'Workspace mismatch' }
+            });
+            vi.mocked(provisionWorkspace).mockResolvedValueOnce({
+                ok: false,
+                status: 409,
+                data: { code: 'WORKSPACE_ID_ALREADY_EXISTS', error: 'Workspace ID already exists' }
+            });
+            const res = await ensureCloudWorkspaceReadyForSyncService(baseHandshakeInput);
+            expect(res.success).toBe(false);
+            expect(res.statusCode).toBe(409);
+            expect(res.error).toContain('already linked to another cloud account');
+            expect(res.error).toContain('grant you access');
+        });
     });
     describe('syncUserGlobalSettingsService transient metadata', () => {
         beforeEach(() => {

package/dist/sync/workspaceRepair.d.ts

@@ -0,0 +1,114 @@
+import type { TaskItem } from '../types.js';
+import type { WorkspaceAssetLinkRole, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+export interface WorkspaceRepairManifestTaskEntry {
+    id: string;
+    archived: boolean;
+    updatedAt: string;
+    createdAt: string;
+    attachmentCount: number;
+}
+export interface WorkspaceRepairManifestDeleteEntry {
+    key: string;
+    deletedAt: string;
+}
+export interface WorkspaceRepairManifestDocumentEntry {
+    path: string;
+    assetId: string | null;
+    taskId: string | null;
+    updatedAt: string;
+    deletedAt: string | null;
+    sha256: string;
+    sizeBytes: number;
+    existsLocally: boolean;
+    source: 'metadata' | 'filesystem';
+}
+export interface WorkspaceRepairManifestAssetEntry {
+    path: string;
+    assetId: string | null;
+    taskId: string | null;
+    kind: 'image' | 'file';
+    updatedAt: string;
+    deletedAt: string | null;
+    sha256: string;
+    sizeBytes: number;
+    existsLocally: boolean;
+    source: 'metadata' | 'filesystem';
+}
+export interface WorkspaceRepairManifest {
+    workspaceId: string;
+    generatedAt: string;
+    tasks: WorkspaceRepairManifestTaskEntry[];
+    deletedTasks: WorkspaceRepairManifestDeleteEntry[];
+    documents: WorkspaceRepairManifestDocumentEntry[];
+    documentDeletes: WorkspaceRepairManifestDeleteEntry[];
+    assets: WorkspaceRepairManifestAssetEntry[];
+    assetDeletes: WorkspaceRepairManifestDeleteEntry[];
+}
+export type WorkspaceRepairIssueCode = 'missing_document_metadata' | 'missing_document_file' | 'stale_document_tombstone' | 'missing_asset_metadata' | 'missing_asset_file' | 'stale_asset_tombstone' | 'stale_asset_link';
+export interface WorkspaceRepairIssue {
+    code: WorkspaceRepairIssueCode;
+    entityKind: 'document' | 'asset' | 'link';
+    path?: string;
+    assetId?: string | null;
+    taskId?: string | null;
+    role?: WorkspaceAssetLinkRole;
+    repairable: boolean;
+    recommendedAction: 'create-metadata' | 'mark-deleted' | 'revive-metadata' | 'delete-link';
+    detail: string;
+}
+export interface WorkspaceRepairScanResult {
+    workspaceId: string;
+    generatedAt: string;
+    snapshot: WorkspaceRepairManifest;
+    issues: WorkspaceRepairIssue[];
+    summary: {
+        totalIssues: number;
+        repairableIssues: number;
+        byCode: Record<string, number>;
+    };
+}
+export interface WorkspaceRepairApplyResult extends WorkspaceRepairScanResult {
+    actionsApplied: Array<{
+        code: WorkspaceRepairIssueCode;
+        path?: string;
+        assetId?: string | null;
+        taskId?: string | null;
+        action: WorkspaceRepairIssue['recommendedAction'];
+        status: 'applied' | 'skipped' | 'failed';
+        detail: string;
+    }>;
+}
+export declare function buildWorkspaceRepairManifest(input: {
+    workspaceId: string;
+    basePath: string;
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+    deletedTasks: Array<{
+        taskId: string;
+        deletedAt: string;
+    }>;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+}): WorkspaceRepairManifest;
+export declare function scanWorkspaceRepair(input: {
+    workspaceId: string;
+    basePath: string;
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+    deletedTasks: Array<{
+        taskId: string;
+        deletedAt: string;
+    }>;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+}): WorkspaceRepairScanResult;
+export declare function applyWorkspaceRepair(input: {
+    workspaceId: string;
+    basePath: string;
+    tasks: TaskItem[];
+    archivedTasks: TaskItem[];
+    deletedTasks: Array<{
+        taskId: string;
+        deletedAt: string;
+    }>;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    upsertDocumentWatermark: (workspaceId: string, path: string, contentHash: string, updatedAt: string) => void;
+}): WorkspaceRepairApplyResult;