@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.89

package/src/domains/implementation-packets.js

@@ -1,3 +1,36 @@
+import { cleanList, cleanText, isPlainObject } from '../utils/text.js';
+
+function looksLikeUuid(value) {
+  const text = cleanText(value);
+  return Boolean(text && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(text));
+}
+
+function countRoadmapProjectionLines(markdown) {
+  const lines = [];
+  let inSummary = false;
+  for (const line of String(markdown || '').split(/\r?\n/)) {
+    if (line.startsWith('## Roadmap Summary')) {
+      inSummary = true;
+      continue;
+    }
+    if (inSummary && line.startsWith('## ')) {
+      break;
+    }
+    if (inSummary && line.startsWith('- ')) {
+      lines.push(line);
+    }
+  }
+  const wanted = [
+    'Total Items',
+    'Total Tasks',
+    'Total Subtasks',
+    'Total Acceptance Checks',
+    'Open Acceptance Checks',
+    'Completion Percentage',
+  ];
+  return lines.filter((line) => wanted.some((label) => line.startsWith(`- ${label}:`)));
+}
+
 export function createImplementationPacketsDomain(client) {
   return {
     importImplementationPacket: (body) => client._request('/api/governed-implementation/packets/import', { method: 'POST', body }),
@@ -11,5 +44,145 @@ export function createImplementationPacketsDomain(client) {
     }),
     getWorkflowImplementationRoadmap: (workflowId) => client._request(`/api/governed-implementation/workflows/${workflowId}/roadmap`),
     getWorkflowResumeContext: (workflowId) => client._request(`/api/governed-implementation/workflows/${workflowId}/resume-context`),
+    importImplementationPacketAndMaterializeRoadmap: async (packetPayload, {
+      importedBy,
+      requestedBy,
+      createdBy,
+      workflowId,
+      bindingRole = 'active',
+      assignedTo,
+      notes,
+      createAcceptanceSubtasks = true,
+    } = {}) => {
+      if (!isPlainObject(packetPayload)) {
+        throw new Error('packetPayload must be a JSON object.');
+      }
+
+      const normalizedImportedBy = cleanText(importedBy) || cleanText(requestedBy) || client.actorId;
+      const normalizedRequestedBy = cleanText(requestedBy) || normalizedImportedBy;
+      const normalizedCreatedBy = cleanText(createdBy) || normalizedRequestedBy;
+
+      const importedPacket = await client.importImplementationPacket({
+        ...packetPayload,
+        imported_by: normalizedImportedBy,
+      });
+      const packetId = cleanText(importedPacket?.packet_id || importedPacket?.packetId || importedPacket?.implementation_packet_key || importedPacket?.implementationPacketKey || packetPayload.packetId || packetPayload.packet_id);
+      const implementationPacketId = cleanText(importedPacket?.implementation_packet_id || importedPacket?.implementationPacketId);
+      if (!implementationPacketId) {
+        throw new Error('Imported implementation packet response must include implementation_packet_id.');
+      }
+      if (!looksLikeUuid(implementationPacketId)) {
+        throw new Error('Imported implementation packet response returned a non-UUID implementation_packet_id.');
+      }
+      const projectReference = client._resolveImplementationPacketProjectReference(packetPayload);
+      if (!projectReference) {
+        throw new Error('Could not resolve a project reference from the packet payload.');
+      }
+      const projectPayload = await client.getProject(projectReference);
+      const projectSummary = isPlainObject(projectPayload?.summary) ? projectPayload.summary : {};
+      const projectId = cleanText(projectSummary.project_id);
+      if (!projectId) {
+        throw new Error('Project id could not be resolved.');
+      }
+
+      const workflowReference = client._resolveImplementationPacketWorkflowReference(packetPayload, {
+        projectSummary,
+        workflowIdOverride: cleanText(workflowId),
+      });
+      if (!workflowReference) {
+        throw new Error('Could not resolve a workflow reference from the packet payload or project summary.');
+      }
+      const resolvedWorkflowId = await client._resolveImplementationPacketWorkflowId(workflowReference);
+      const workflowSlug = cleanText(projectSummary.workflow_slug);
+
+      const binding = await client.bindImplementationPacketToWorkflow(resolvedWorkflowId, {
+        packet_id: packetId,
+        binding_role: cleanText(bindingRole) || 'active',
+        created_by: normalizedCreatedBy,
+        notes: cleanText(notes),
+      });
+
+      const taskSurface = await client.ensureProjectRoadmapTaskSurface(projectId, {
+        requestedBy: normalizedRequestedBy,
+        assignedTo,
+        createAcceptanceSubtasks,
+      });
+
+      const roadmapReport = await client.getProjectImplementationRoadmapReport(projectId);
+      const roadmapMarkdown = await client.downloadProjectImplementationRoadmapReportMarkdown(projectId);
+      const phases = Array.isArray(packetPayload.phases) ? packetPayload.phases.filter(isPlainObject) : [];
+      const roadmapItems = phases.flatMap((phase) => (
+        Array.isArray(phase.items) ? phase.items.filter(isPlainObject) : []
+      ));
+      const taskRows = Array.isArray(taskSurface?.task_surfaces) ? taskSurface.task_surfaces.filter(isPlainObject) : [];
+      const subtaskRows = taskRows.filter((task) => cleanText(task.parent_task_id) !== null);
+      const acceptanceCheckCount = roadmapItems.reduce(
+        (total, item) => total + (Array.isArray(item.acceptanceChecks) ? item.acceptanceChecks.filter(Boolean).length : 0),
+        0,
+      );
+
+      return {
+        status: 'materialized',
+        project_id: projectId,
+        project_slug: cleanText(projectSummary.project_slug),
+        workflow_id: resolvedWorkflowId,
+        workflow_slug: workflowSlug,
+        implementation_packet_id: implementationPacketId,
+        implementation_packet_key: packetId,
+        binding,
+        task_surface: taskSurface,
+        roadmap_projection: {
+          report: roadmapReport,
+          markdown: roadmapMarkdown,
+          count_lines: countRoadmapProjectionLines(roadmapMarkdown),
+          phase_count: phases.length,
+          roadmap_item_count: roadmapItems.length,
+          task_count: taskRows.length,
+          subtask_count: subtaskRows.length,
+          acceptance_check_count: acceptanceCheckCount,
+        },
+      };
+    },
+    _resolveImplementationPacketProjectReference: (packetPayload) => cleanText(packetPayload.projectId)
+      || cleanText(packetPayload.project_id)
+      || cleanText(packetPayload.projectSlug)
+      || cleanText(packetPayload.project_slug)
+      || cleanText(packetPayload?.scope?.projectId)
+      || cleanText(packetPayload?.scope?.project_id)
+      || cleanText(packetPayload?.scope?.projectSlug)
+      || cleanText(packetPayload?.scope?.project_slug)
+      || cleanText(packetPayload?.system?.slug),
+    _resolveImplementationPacketWorkflowReference: (packetPayload, { projectSummary, workflowIdOverride } = {}) => {
+      if (workflowIdOverride) return workflowIdOverride;
+      return cleanText(packetPayload.workflowId)
+        || cleanText(packetPayload.workflow_id)
+        || cleanText(packetPayload.workflowSlug)
+        || cleanText(packetPayload.workflow_slug)
+        || cleanText(packetPayload?.scope?.workflowId)
+        || cleanText(packetPayload?.scope?.workflow_id)
+        || cleanText(packetPayload?.scope?.workflowSlug)
+        || cleanText(packetPayload?.scope?.workflow_slug)
+        || cleanText(projectSummary?.workflow_id)
+        || cleanText(projectSummary?.workflow_slug);
+    },
+    _resolveImplementationPacketWorkflowId: async (workflowReference) => {
+      const normalized = cleanText(workflowReference);
+      if (!normalized) {
+        throw new Error('workflow reference is required.');
+      }
+      const workflow = await client.getWorkflow(normalized);
+      if (workflow) {
+        return cleanText(workflow.workflow_id) || cleanText(workflow.workflowId) || normalized;
+      }
+      const workflowList = await client.listWorkflows();
+      const workflows = Array.isArray(workflowList) ? workflowList : workflowList?.workflows;
+      const matches = Array.isArray(workflows)
+        ? workflows.filter((item) => cleanText(item?.slug) === normalized)
+        : [];
+      if (matches.length === 1) {
+        return cleanText(matches[0].workflow_id) || cleanText(matches[0].workflowId) || normalized;
+      }
+      throw new Error(`Workflow not found: ${normalized}`);
+    },
   };
 }

package/src/domains/implementation-tasks.js

@@ -1,10 +1,129 @@
 export function createImplementationTasksDomain(client) {
   return {
-    createImplementationTask: (implementationItemId, request) => client.createImplementationTask(implementationItemId, request),
-    listImplementationTasks: (implementationItemId) => client.listImplementationTasks(implementationItemId),
-    listImplementationSubtasks: (taskId) => client.listImplementationSubtasks(taskId),
-    updateImplementationTask: (taskId, updates) => client.updateImplementationTask(taskId, updates),
-    assignImplementationTask: (taskId, request) => client.assignImplementationTask(taskId, request),
-    completeImplementationTask: (taskId, request) => client.completeImplementationTask(taskId, request),
+    createImplementationTask: (implementationItemId, request) => createImplementationTask(client, implementationItemId, request),
+    listImplementationTasks: (implementationItemId) => listImplementationTasks(client, implementationItemId),
+    listImplementationSubtasks: (taskId) => listImplementationSubtasks(client, taskId),
+    updateImplementationTask: (taskId, updates) => updateImplementationTask(client, taskId, updates),
+    assignImplementationTask: (taskId, request) => assignImplementationTask(client, taskId, request),
+    completeImplementationTask: (taskId, request) => completeImplementationTask(client, taskId, request),
   };
 }
+
+export async function createImplementationTask(client, implementationItemId, {
+  title,
+  implementationPacketId,
+  description,
+  priority,
+  assignedTo,
+  assignedBy,
+  dueAt,
+  sortOrder,
+  notes,
+  createdBy,
+  parentTaskId,
+  claimId,
+  claimProjectId,
+  projectId,
+  claimedItemId,
+  workflowRunId,
+  agentSessionId,
+  allowedMutationSurfaces,
+  acknowledgedReminders,
+  executionIntent,
+  executionType,
+  executionPurpose,
+} = {}) {
+  const normalizedClaimId = String(claimId || '').trim() || null;
+  const normalizedClaimProjectId = String(claimProjectId || projectId || '').trim() || null;
+  const normalizedClaimedItemId = String(claimedItemId || implementationItemId || '').trim() || null;
+  const normalizedWorkflowRunId = String(workflowRunId || '').trim() || null;
+  const normalizedAgentSessionId = String(agentSessionId || '').trim() || null;
+  const normalizedAllowedMutationSurfaces = Array.isArray(allowedMutationSurfaces) && allowedMutationSurfaces.length > 0
+    ? allowedMutationSurfaces
+    : ['project_roadmap_task'];
+  const normalizedAcknowledgedReminders = Array.isArray(acknowledgedReminders)
+    ? acknowledgedReminders
+    : undefined;
+  const normalizedExecutionIntent = (() => {
+    if (executionIntent && typeof executionIntent === 'object') {
+      const execution_type = String(executionIntent.execution_type || executionIntent.executionType || '').trim();
+      const execution_purpose = String(executionIntent.execution_purpose || executionIntent.executionPurpose || '').trim();
+      if (execution_type || execution_purpose) {
+        return {
+          ...(execution_type ? { execution_type } : {}),
+          ...(execution_purpose ? { execution_purpose } : {}),
+        };
+      }
+    }
+    const normalizedExecutionType = String(executionType || '').trim() || 'implementation_task';
+    const normalizedExecutionPurpose = String(executionPurpose || title || '').trim() || 'implementation task';
+    return {
+      execution_type: normalizedExecutionType,
+      execution_purpose: normalizedExecutionPurpose,
+    };
+  })();
+  await client._assertExecutionEligibility({
+    claim_id: normalizedClaimId,
+    claim_project_id: normalizedClaimProjectId,
+    claimed_item_id: normalizedClaimedItemId,
+    workflow_run_id: normalizedWorkflowRunId,
+    agent_session_id: normalizedAgentSessionId,
+    allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
+    acknowledged_reminders: normalizedAcknowledgedReminders || [],
+    requested_mutation_surface: 'project_roadmap_task',
+    verification_required: true,
+  });
+  return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`, {
+    method: 'POST',
+    body: {
+      title,
+      implementation_packet_id: implementationPacketId,
+      description,
+      priority,
+      assigned_to: assignedTo,
+      assigned_by: assignedBy,
+      due_at: dueAt,
+      sort_order: sortOrder,
+      notes,
+      created_by: createdBy,
+      parent_task_id: parentTaskId,
+      claim_id: normalizedClaimId,
+      claim_project_id: normalizedClaimProjectId,
+      claimed_item_id: normalizedClaimedItemId,
+      workflow_run_id: normalizedWorkflowRunId,
+      agent_session_id: normalizedAgentSessionId,
+      allowed_mutation_surfaces: normalizedAllowedMutationSurfaces,
+      acknowledged_reminders: normalizedAcknowledgedReminders,
+      execution_intent: normalizedExecutionIntent,
+    },
+  });
+}
+
+export function listImplementationTasks(client, implementationItemId) {
+  return client._request(`/api/operator/implementation-items/${implementationItemId}/tasks`);
+}
+
+export function listImplementationSubtasks(client, taskId) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/subtasks`);
+}
+
+export function updateImplementationTask(client, taskId, updates) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}`, {
+    method: 'PATCH',
+    body: updates,
+  });
+}
+
+export function assignImplementationTask(client, taskId, request = {}) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/assign`, {
+    method: 'POST',
+    body: { assigned_to: request.assignedTo, assigned_by: request.assignedBy },
+  });
+}
+
+export function completeImplementationTask(client, taskId, request = {}) {
+  return client._request(`/api/operator/implementation-item-tasks/${taskId}/complete`, {
+    method: 'POST',
+    body: { completed_by: request.completedBy },
+  });
+}

package/src/domains/portfolio.js

@@ -1,3 +1,5 @@
+import { cleanText, isPlainObject } from '../utils/text.js';
+
 export function createPortfolioDomain(client) {
   return {
     getPortfolioStatus: (request) => client.getPortfolioStatus(request),
@@ -6,6 +8,128 @@ export function createPortfolioDomain(client) {
     getPortfolioProject: (projectId) => client.getPortfolioProject(projectId),
     getPortfolioReport: () => client.getPortfolioReport(),
     getPortfolioBundle: () => client.getPortfolioBundle(),
-    getPortfolioClosureReadiness: (request) => client.getPortfolioClosureReadiness(request),
+    getPortfolioClosureReadiness: async ({
+      projectLimit = 25,
+      includeInactive = false,
+      includeLogaPortfolioProjection = false,
+      includeLogaRoadmapProjections = false,
+    } = {}) => {
+      const portfolioBundle = await client.getPortfolioBundle();
+      const projectListPayload = await client.listProjects({
+        limit: projectLimit,
+        includeInactive,
+      });
+
+      const bundleProjects = Array.isArray(portfolioBundle?.projects)
+        ? portfolioBundle.projects.filter((project) => isPlainObject(project))
+        : [];
+      const listedProjects = Array.isArray(projectListPayload?.projects)
+        ? projectListPayload.projects.filter((project) => isPlainObject(project))
+        : Array.isArray(projectListPayload)
+          ? projectListPayload.filter((project) => isPlainObject(project))
+          : [];
+      const activeProjects = listedProjects.length > 0 ? listedProjects : bundleProjects;
+      const logaPortfolioProjection = includeLogaPortfolioProjection
+        ? await client.getLogaProjectPortfolioProjection()
+        : null;
+      const logaRoadmapProjections = {};
+
+      const projectReadiness = [];
+      for (const project of activeProjects) {
+        const projectId = cleanText(project.project_id) || cleanText(project.projectId);
+        if (!projectId) {
+          continue;
+        }
+
+        const roadmapSummaryPayload = await client.getProjectRoadmapSummary(projectId);
+        const roadmapSummary = isPlainObject(roadmapSummaryPayload?.summary) ? roadmapSummaryPayload.summary : {};
+        const activeItemPayload = await client.getProjectRoadmapActiveItem(projectId);
+        const activeItem = isPlainObject(activeItemPayload?.active_item)
+          ? activeItemPayload.active_item
+          : isPlainObject(activeItemPayload)
+            ? activeItemPayload
+            : {};
+        const openTasksPayload = await client.listProjectOpenTasks(projectId);
+        const openTasks = Array.isArray(openTasksPayload?.tasks)
+          ? openTasksPayload.tasks.filter((task) => isPlainObject(task))
+          : Array.isArray(openTasksPayload)
+            ? openTasksPayload.filter((task) => isPlainObject(task))
+            : [];
+
+        const activeItemStatus = cleanText(activeItem.item_status) || cleanText(activeItem.status);
+        const completionPercentage = Number(
+          roadmapSummary.completion_percentage
+          ?? roadmapSummary.completion_pct
+          ?? roadmapSummary.progress_percentage
+          ?? 0,
+        );
+        const totalItems = Number(
+          roadmapSummary.total_items
+          ?? roadmapSummary.item_count
+          ?? roadmapSummary.total_count
+          ?? 0,
+        );
+        const openItems = Number(
+          roadmapSummary.open_items
+          ?? roadmapSummary.open_item_count
+          ?? roadmapSummary.remaining_items
+          ?? openTasks.length,
+        );
+        const terminalStatuses = new Set(['accepted', 'verified', 'done', 'completed', 'closed']);
+        const activeItemReady = !activeItemStatus || terminalStatuses.has(activeItemStatus.toLowerCase());
+        const projectReady = openItems === 0 && openTasks.length === 0 && activeItemReady && completionPercentage >= 100;
+        const blockingReason = projectReady
+          ? null
+          : [
+              openTasks.length > 0 ? `${openTasks.length} open task(s) remain` : null,
+              openItems > 0 ? `${openItems} roadmap item(s) remain open` : null,
+              !activeItemReady ? `active item status is ${activeItemStatus || 'missing'}` : null,
+              completionPercentage < 100 ? `completion is ${completionPercentage.toFixed(1)}%` : null,
+            ].filter(Boolean).join('; ') || 'portfolio closure readiness is not satisfied';
+
+        const roadmapCompletion = {
+          completion_percentage: completionPercentage,
+          total_items: totalItems,
+          open_items: openItems,
+          completed_items: Math.max(totalItems - openItems, 0),
+        };
+        const projectReadinessEntry = {
+          project: {
+            project_id: projectId,
+            project_name: cleanText(project.project_name) || cleanText(project.projectName) || null,
+            project_slug: cleanText(project.project_slug) || cleanText(project.projectSlug) || null,
+            process_status: cleanText(project.process_status) || cleanText(project.processStatus) || null,
+            charter_status: cleanText(project.charter_status) || cleanText(project.charterStatus) || null,
+          },
+          roadmap_completion: roadmapCompletion,
+          active_item: activeItem,
+          open_task_count: openTasks.length,
+          closure_ready: projectReady,
+          blocking_reason: blockingReason,
+        };
+        if (includeLogaRoadmapProjections) {
+          projectReadinessEntry.loga_roadmap_projection = await client.getLogaProjectRoadmapProjection(projectId);
+          logaRoadmapProjections[projectId] = projectReadinessEntry.loga_roadmap_projection;
+        }
+        projectReadiness.push(projectReadinessEntry);
+      }
+
+      const closureReady = projectReadiness.length === 0 || projectReadiness.every((project) => project.closure_ready === true);
+      const blockingProject = projectReadiness.find((project) => project.closure_ready !== true);
+
+      return {
+        portfolio_summary: isPlainObject(portfolioBundle?.summary) ? portfolioBundle.summary : {},
+        portfolio_bundle: portfolioBundle,
+        active_projects: projectReadiness,
+        closure_readiness: closureReady,
+        blocking_reason: closureReady ? null : `${cleanText(blockingProject?.project?.project_name) || cleanText(blockingProject?.project?.project_id) || 'project'}: ${blockingProject?.blocking_reason || 'closure readiness is not satisfied'}`,
+        blocking_project_id: closureReady ? null : cleanText(blockingProject?.project?.project_id),
+        blocking_project_name: closureReady ? null : cleanText(blockingProject?.project?.project_name),
+        project_count: projectReadiness.length,
+        open_task_count: projectReadiness.reduce((total, project) => total + Number(project.open_task_count || 0), 0),
+        loga_portfolio_projection: logaPortfolioProjection,
+        loga_roadmap_projections: includeLogaRoadmapProjections ? logaRoadmapProjections : null,
+      };
+    },
   };
 }

package/src/domains/project-chartering.js

@@ -1,3 +1,6 @@
+import { isPlainObject } from '../utils/text.js';
+import { normalizeTaskBindingPolicy } from '../utils/task-binding.js';
+
 export function createProjectCharteringDomain(client) {
   return {
     createProjectDelivery: (body = {}) => client._request('/api/project-delivery', { method: 'POST', body }),
@@ -29,6 +32,21 @@ export function createProjectCharteringDomain(client) {
         body,
       });
     },
+    routeImplementationItem: (implementationItemId, body = {}) => {
+      if (!implementationItemId) throw new Error('implementationItemId is required.');
+      const normalizedBody = isPlainObject(body)
+        ? {
+            ...body,
+            ...(isPlainObject(body.task_binding)
+              ? { task_binding: normalizeTaskBindingPolicy(body.task_binding) }
+              : {}),
+          }
+        : body;
+      return client._request(`/api/governed-implementation/items/${encodeURIComponent(implementationItemId)}/routing`, {
+        method: 'PATCH',
+        body: normalizedBody,
+      });
+    },
     createProjectCharter: (request = {}) => client._request('/api/projects/charter', {
       method: 'POST',
       body: {

package/src/domains/project-reports.js

@@ -0,0 +1,14 @@
+export function createProjectReportsDomain(client) {
+  return {
+    getProjectCharterReport: (projectId) => client._request(`/api/operator/projects/${projectId}/charter/report`),
+    createProjectMarkdownDownload: (projectId, request = {}) => client._request(`/api/operator/projects/${projectId}/markdown-report-downloads`, {
+      method: 'POST',
+      body: {
+        report_type: request.reportType,
+        include_markdown: request.includeMarkdown ?? false,
+      },
+    }),
+    downloadProjectMarkdownReport: (projectId, reportType) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/${reportType}/download`),
+    downloadProjectCharterReportMarkdown: (projectId) => client._requestText(`/api/operator/projects/${projectId}/markdown-reports/charter/download`),
+  };
+}

package/src/domains/project-resume.js

@@ -0,0 +1,18 @@
+export function createProjectResumeDomain(client) {
+  return {
+    resumeProjectWork: (request = {}) => {
+      const normalizedProjectIdentifier = String(request.projectIdentifier || request.projectId || '').trim();
+      if (!normalizedProjectIdentifier) {
+        throw new Error('projectIdentifier is required.');
+      }
+      return client._request(`/api/operator/projects/${encodeURIComponent(normalizedProjectIdentifier)}/resume-context`, {
+        query: {
+          actor_mode: request.actorMode,
+          execution_intent: request.executionIntent,
+          require_claim: request.requireClaim,
+          workflow_run_limit: request.workflowRunLimit,
+        },
+      });
+    },
+  };
+}