@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/server/routes/workflows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workflow template, assignment, and execution HTTP boundary.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { TaskforceCore } from '../../core/Taskforce.js';
+import { WorkflowAssignmentService } from '../../core/WorkflowAssignmentService.js';
+import { WorkflowExecutionService } from '../../core/WorkflowExecutionService.js';
+import { WorkflowTemplateService } from '../../core/WorkflowTemplateService.js';
+import { type RouteHandler } from './primitives.js';
+type TemplateService = Pick<WorkflowTemplateService, 'createWorkflow' | 'listWorkflows' | 'getWorkflow' | 'saveDraft' | 'updateDraftMetadata' | 'replaceDraftSteps' | 'publishDraft' | 'createDraft'>;
+type AssignmentService = Pick<WorkflowAssignmentService, 'assignWorkflow' | 'replacePendingWorkflow' | 'removePendingWorkflow' | 'getActiveAssignment' | 'getLatestAssignment'>;
+type ExecutionService = Pick<WorkflowExecutionService, 'getExecutionState' | 'transitionExecution' | 'completeCurrentStep'>;
+export interface WorkflowsRouteDependencies {
+    addRoute: (method: string, path: string, handler: RouteHandler) => void;
+    ensureAppAccess: (req: IncomingMessage, res: ServerResponse) => boolean;
+    ensureAuthenticatedUser: (req: IncomingMessage) => boolean;
+    requireCloudRuntime: (res: ServerResponse, feature: string) => boolean;
+    requestWorkspaceId: (req: IncomingMessage) => string;
+    resolveAuthenticatedUserId: (req: IncomingMessage) => string;
+    core?: TaskforceCore;
+    templateService?: TemplateService;
+    assignmentService?: AssignmentService;
+    executionService?: ExecutionService;
+}
+export declare function registerWorkflowRoutes(deps: WorkflowsRouteDependencies): void;
+export {};

package/dist/server/routes/workflows.js

@@ -0,0 +1,500 @@
+/**
+ * Workflow template, assignment, and execution HTTP boundary.
+ */
+import { WorkflowAssignmentService, WorkflowAssignmentServiceError, } from '../../core/WorkflowAssignmentService.js';
+import { WorkflowExecutionService, WorkflowExecutionServiceError, } from '../../core/WorkflowExecutionService.js';
+import { WorkflowTemplateService, WorkflowTemplateServiceError, } from '../../core/WorkflowTemplateService.js';
+import { WorkflowStore } from '../../storage/workflowStore.js';
+import { createDurableTaskHttpRootMutationRouter } from '../../sync/v3/durableTaskHttpRootMutationRouter.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncDurabilityStore, } from '../../sync/v3/syncDurabilityStore.js';
+import { normalizeWorkflowAssignmentSyncRecord } from '../../sync/v3/workflowAssignmentSync.js';
+import { createDurableWorkflowRuntimeMutationRouter, resolveWorkflowRuntimeMutationCapability, } from '../../sync/v3/durableWorkflowRuntimeMutationRouter.js';
+import { parseJsonBody, resolveHttpErrorStatusCode } from './primitives.js';
+import { requestRuntimeMode } from './shared.js';
+function writeJson(res, statusCode, payload) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+}
+function errorStatus(error) {
+    if (error instanceof WorkflowTemplateServiceError
+        || error instanceof WorkflowAssignmentServiceError
+        || error instanceof WorkflowExecutionServiceError) {
+        switch (error.code) {
+            case 'workflow_not_found':
+            case 'task_not_found':
+            case 'version_not_found':
+            case 'execution_not_found':
+                return 404;
+            case 'draft_not_found':
+            case 'draft_already_exists':
+            case 'published_version_immutable':
+            case 'workflow_retired':
+            case 'version_not_published':
+            case 'version_mismatch':
+            case 'active_execution_exists':
+            case 'assignment_locked':
+            case 'invalid_transition':
+            case 'idempotency_conflict':
+            case 'current_step_missing':
+            case 'step_owner_required':
+            case 'next_step_owner_invalid':
+                return 409;
+            case 'step_owner_mismatch':
+                return 403;
+            default:
+                return 400;
+        }
+    }
+    return resolveHttpErrorStatusCode(error, 500);
+}
+function writeError(res, error) {
+    const statusCode = errorStatus(error);
+    writeJson(res, statusCode, {
+        success: false,
+        error: statusCode >= 500
+            ? 'Unable to process workflow request.'
+            : String(error?.message || error || 'Workflow request failed.'),
+        ...(error?.code ? { code: String(error.code) } : {}),
+    });
+}
+export function registerWorkflowRoutes(deps) {
+    const { addRoute, ensureAppAccess, ensureAuthenticatedUser, requireCloudRuntime, requestWorkspaceId, resolveAuthenticatedUserId, core, } = deps;
+    let templateService = deps.templateService || null;
+    let assignmentService = deps.assignmentService || null;
+    let executionService = deps.executionService || null;
+    const getServices = () => {
+        if (templateService && assignmentService && executionService) {
+            return { templateService, assignmentService, executionService };
+        }
+        if (!core)
+            throw new Error('Workflow services are unavailable.');
+        const store = new WorkflowStore(core.getDatabaseAdapter(), core.getTenantId());
+        templateService ||= new WorkflowTemplateService(store);
+        assignmentService ||= new WorkflowAssignmentService(store);
+        executionService ||= new WorkflowExecutionService(store, {
+            listAssignableActors: (workspaceId) => core.listAssignableActors(workspaceId),
+            getTask: (workspaceId, taskId) => core.getTask(taskId, workspaceId),
+        });
+        return { templateService, assignmentService, executionService };
+    };
+    const guard = (req, res) => {
+        if (!ensureAppAccess(req, res))
+            return false;
+        if (requestRuntimeMode(req) === 'local')
+            return true;
+        if (ensureAuthenticatedUser(req))
+            return true;
+        writeJson(res, 401, { success: false, error: 'Authentication required.', code: 'AUTH_REQUIRED' });
+        return false;
+    };
+    const durableWorkflowHttpEnabled = (req) => (resolveWorkflowRuntimeMutationCapability({
+        runtimeMode: requestRuntimeMode(req),
+        surface: 'http',
+    }));
+    const executionMutationGuard = (req, res) => {
+        if (!guard(req, res))
+            return false;
+        return durableWorkflowHttpEnabled(req) || requireCloudRuntime(res, 'Workflow execution');
+    };
+    const workspaceIdFor = (req) => String(requestWorkspaceId(req) || '').trim() || 'default';
+    addRoute('GET', '/api/taskforce/workflows', async (req, res) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const workflows = getServices().templateService.listWorkflows(workspaceIdFor(req));
+            writeJson(res, 200, { success: true, workflows });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflows', async (req, res) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workflow = getServices().templateService.createWorkflow({
+                workspaceId: workspaceIdFor(req),
+                name: body.name,
+                description: body.description,
+                steps: body.steps,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 201, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('GET', '/api/taskforce/workflows/:workflowId', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const workflow = getServices().templateService.getWorkflow(workspaceIdFor(req), params.workflowId);
+            writeJson(res, 200, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('PUT', '/api/taskforce/workflows/:workflowId/draft', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workflow = getServices().templateService.saveDraft({
+                workspaceId: workspaceIdFor(req),
+                templateId: params.workflowId,
+                name: body.name,
+                description: body.description,
+                steps: body.steps,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 200, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('PATCH', '/api/taskforce/workflows/:workflowId/draft', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workflow = getServices().templateService.updateDraftMetadata({
+                workspaceId: workspaceIdFor(req),
+                templateId: params.workflowId,
+                name: body.name,
+                description: body.description,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 200, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('PUT', '/api/taskforce/workflows/:workflowId/draft/steps', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            resolveAuthenticatedUserId(req);
+            const workflow = getServices().templateService.replaceDraftSteps({
+                workspaceId: workspaceIdFor(req),
+                templateId: params.workflowId,
+                steps: body.steps,
+            });
+            writeJson(res, 200, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflows/:workflowId/publish', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const workflow = getServices().templateService.publishDraft({
+                workspaceId: workspaceIdFor(req),
+                templateId: params.workflowId,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 200, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflows/:workflowId/draft', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const workflow = getServices().templateService.createDraft({
+                workspaceId: workspaceIdFor(req),
+                templateId: params.workflowId,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 201, { success: true, workflow });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/tasks/:taskId/workflow', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const assignment = getServices().assignmentService.assignWorkflow({
+                workspaceId: workspaceIdFor(req),
+                taskId: params.taskId,
+                workflowTemplateId: body.workflowTemplateId,
+                workflowVersionId: body.workflowVersionId,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 201, { success: true, assignment });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('PUT', '/api/taskforce/tasks/:taskId/workflow', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const assignment = getServices().assignmentService.replacePendingWorkflow({
+                workspaceId: workspaceIdFor(req),
+                taskId: params.taskId,
+                workflowTemplateId: body.workflowTemplateId,
+                workflowVersionId: body.workflowVersionId,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 200, { success: true, assignment });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('DELETE', '/api/taskforce/tasks/:taskId/workflow', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            getServices().assignmentService.removePendingWorkflow({
+                workspaceId: workspaceIdFor(req),
+                taskId: params.taskId,
+                actorId: resolveAuthenticatedUserId(req),
+            });
+            writeJson(res, 200, { success: true, assignment: null });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('GET', '/api/taskforce/tasks/:taskId/workflow', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const assignment = getServices().assignmentService.getLatestAssignment(workspaceIdFor(req), params.taskId);
+            writeJson(res, 200, { success: true, assignment });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('GET', '/api/taskforce/workflow-executions/:executionId', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        try {
+            const state = getServices().executionService.getExecutionState(workspaceIdFor(req), params.executionId);
+            writeJson(res, 200, { success: true, state });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflow-executions/:executionId/transitions', async (req, res, params) => {
+        if (!executionMutationGuard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = workspaceIdFor(req);
+            const actorId = resolveAuthenticatedUserId(req);
+            const result = durableWorkflowHttpEnabled(req) && core
+                ? createDurableWorkflowRuntimeMutationRouter({
+                    core,
+                    runtimeMode: requestRuntimeMode(req),
+                    surface: 'http',
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    actorId,
+                    actorType: 'user',
+                    operationId: body.idempotencyKey,
+                }).transition({
+                    executionId: params.executionId,
+                    action: body.action,
+                    expectedStatus: body.expectedStatus,
+                    details: body.details,
+                })
+                : getServices().executionService.transitionExecution({
+                    workspaceId,
+                    executionId: params.executionId,
+                    action: body.action,
+                    actorId,
+                    idempotencyKey: body.idempotencyKey,
+                    details: body.details,
+                });
+            writeJson(res, 200, { success: true, result });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflow-executions/:executionId/complete-step', async (req, res, params) => {
+        if (!executionMutationGuard(req, res))
+            return;
+        try {
+            const body = await parseJsonBody(req);
+            const workspaceId = workspaceIdFor(req);
+            const actorId = resolveAuthenticatedUserId(req);
+            if (durableWorkflowHttpEnabled(req) && core) {
+                const result = createDurableWorkflowRuntimeMutationRouter({
+                    core,
+                    runtimeMode: requestRuntimeMode(req),
+                    surface: 'http',
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    actorId,
+                    actorType: 'user',
+                    operationId: body.idempotencyKey,
+                }).completeStep({
+                    executionId: params.executionId,
+                    expectedStepId: body.expectedStepId,
+                    evidenceCommentId: body.evidenceCommentId,
+                });
+                const taskRevision = result.authoritative?.revisions.find((revision) => revision.projection === 'task/root-v1');
+                const taskAuthoritative = result.authoritative?.task && taskRevision
+                    ? {
+                        payload: result.authoritative.task.payload,
+                        entityRevision: taskRevision.entityRevision,
+                        lifecycleRevision: taskRevision.lifecycleRevision,
+                        sequence: taskRevision.sequence,
+                        canonicalFingerprint: taskRevision.canonicalFingerprint,
+                    }
+                    : null;
+                writeJson(res, 200, {
+                    success: true,
+                    result: { ...result, taskAuthoritative },
+                });
+                return;
+            }
+            const postCommitNotifications = [];
+            const service = deps.executionService || (() => {
+                if (!core)
+                    throw new Error('Workflow services are unavailable.');
+                const store = new WorkflowStore(core.getDatabaseAdapter(), core.getTenantId());
+                return new WorkflowExecutionService(store, {
+                    listAssignableActors: (candidateWorkspaceId) => core.listAssignableActors(candidateWorkspaceId),
+                    getTask: (candidateWorkspaceId, taskId) => core.getTask(taskId, candidateWorkspaceId),
+                    reassignTask: ({ taskId, assigneeId, idempotencyKey }) => (createDurableTaskHttpRootMutationRouter({
+                        core,
+                        runtimeMode: 'cloud',
+                        tenantId: core.getTenantId(),
+                        workspaceId,
+                        operationId: `${idempotencyKey}:task-reassign`,
+                        actorRef: actorId,
+                        deferPostCommitNotification: (notify) => postCommitNotifications.push(notify),
+                    }).update(taskId, { assignee: assigneeId }, 'manual')),
+                });
+            })();
+            const result = service.completeCurrentStep({
+                workspaceId,
+                executionId: params.executionId,
+                actorId,
+                expectedStepId: body.expectedStepId,
+                evidenceCommentId: body.evidenceCommentId,
+                idempotencyKey: body.idempotencyKey,
+            });
+            let taskAuthoritative = null;
+            if (result.taskSnapshot) {
+                if (!core)
+                    throw new Error('Workflow task synchronization is unavailable.');
+                const ownership = new WorkspaceSyncDurabilityStore(core.getDatabaseAdapter())
+                    .readWorkspaceDomainOwnership({
+                    tenantId: core.getTenantId(),
+                    workspaceId,
+                    domain: 'task',
+                    entityId: result.taskSnapshot.id,
+                });
+                if (!ownership.owned || !ownership.lastSequence || !ownership.canonicalFingerprint) {
+                    throw new Error('Workflow task synchronization coordinates are unavailable.');
+                }
+                taskAuthoritative = {
+                    payload: result.taskSnapshot,
+                    entityRevision: ownership.entityRevision,
+                    lifecycleRevision: ownership.lifecycleRevision,
+                    sequence: ownership.lastSequence,
+                    canonicalFingerprint: ownership.canonicalFingerprint,
+                };
+            }
+            writeJson(res, 200, { success: true, result: { ...result, taskAuthoritative } });
+            for (const notify of postCommitNotifications) {
+                try {
+                    notify();
+                }
+                catch (error) {
+                    console.warn('[Taskforce] Workflow task reassignment notification failed.', error);
+                }
+            }
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+    addRoute('POST', '/api/taskforce/workflow-executions/:executionId/apply-cloud-state', async (req, res, params) => {
+        if (!guard(req, res))
+            return;
+        if (requestRuntimeMode(req) !== 'local') {
+            writeJson(res, 400, {
+                success: false,
+                error: 'Cloud workflow state can only be installed in local runtime.',
+                code: 'LOCAL_RUNTIME_REQUIRED',
+            });
+            return;
+        }
+        try {
+            if (!core)
+                throw new Error('Workflow services are unavailable.');
+            const body = await parseJsonBody(req);
+            const assignment = normalizeWorkflowAssignmentSyncRecord(body.assignment);
+            if (assignment.execution.id !== params.executionId) {
+                throw new WorkflowExecutionServiceError('invalid_input', 'Workflow execution identity does not match.');
+            }
+            const taskAuthoritative = body.taskAuthoritative && typeof body.taskAuthoritative === 'object'
+                && !Array.isArray(body.taskAuthoritative)
+                ? body.taskAuthoritative
+                : null;
+            const authoritativeTask = taskAuthoritative?.payload
+                || (body.task && typeof body.task === 'object' && !Array.isArray(body.task) ? body.task : null);
+            if (authoritativeTask
+                && String(authoritativeTask.id || '').trim() !== assignment.execution.taskId) {
+                throw new WorkflowExecutionServiceError('invalid_input', 'Workflow task identity does not match.');
+            }
+            if (taskAuthoritative && authoritativeTask
+                && fingerprintWorkspaceSyncPayload(authoritativeTask) !== taskAuthoritative.canonicalFingerprint) {
+                throw new WorkflowExecutionServiceError('invalid_input', 'Workflow task fingerprint does not match.');
+            }
+            const workspaceId = workspaceIdFor(req);
+            core.getDatabaseAdapter().transaction(() => {
+                if (taskAuthoritative && authoritativeTask && typeof authoritativeTask === 'object' && !Array.isArray(authoritativeTask)) {
+                    const store = new WorkspaceSyncDurabilityStore(core.getDatabaseAdapter());
+                    store.applyReplicatedEntityRevision({
+                        tenantId: core.getTenantId(),
+                        workspaceId,
+                        domain: 'task',
+                        entityId: assignment.execution.taskId,
+                        sequence: taskAuthoritative.sequence,
+                        entityRevision: taskAuthoritative.entityRevision,
+                        lifecycleRevision: taskAuthoritative.lifecycleRevision,
+                        canonicalFingerprint: taskAuthoritative.canonicalFingerprint,
+                        now: new Date().toISOString(),
+                        metadataOwned: true,
+                        applyMutation: () => core.installWorkspaceSyncV3TaskRootAuthoritativeForSync(authoritativeTask, workspaceId),
+                    });
+                }
+                else if (authoritativeTask && typeof authoritativeTask === 'object' && !Array.isArray(authoritativeTask)) {
+                    core.installWorkspaceSyncV3TaskRootAuthoritativeForSync(authoritativeTask, workspaceId);
+                }
+                new WorkflowStore(core.getDatabaseAdapter(), core.getTenantId()).installAssignmentForSync(workspaceId, assignment, { authority: 'cloud-execution', expectedTaskId: assignment.execution.taskId });
+            })();
+            writeJson(res, 200, {
+                success: true,
+                task: core.getTask(assignment.execution.taskId, workspaceId),
+            });
+        }
+        catch (error) {
+            writeError(res, error);
+        }
+    });
+}

package/dist/server/routes.d.ts

@@ -43,18 +43,13 @@ export interface Route {
  * - GET /api/taskforce/taxonomies
  * - POST /api/taskforce/taxonomies
  *
- * **Workflow Settings**
- * - GET /api/taskforce/approaches
- * - POST /api/taskforce/approaches
- *
  * **Templates & Setup**
  * - GET /api/taskforce/initiative-templates
  * - POST /api/taskforce/initiative-templates/create
  *
- * **Advanced Features (3 routes)**
+ * **Advanced Features**
  * - GET /api/taskforce/folders
  * - POST /api/taskforce/validate-paths
- * - POST /api/taskforce/export-resources
  * - GET /api/taskforce/health
  */
 export declare function createRoutes(core: TaskforceCore, context?: RouteContext): Route[];