@bpmsoftwaresolutions/ai-engine-client 1.1.35 → 1.1.36

package/README.md

@@ -374,7 +374,7 @@ await client.importImplementationPacket({
 });
 ```
 
-The package does not auto-convert nested human planning structures like `tasks` and `subtasks` into durable implementation-item tasks. To create persisted task records after import, use `ensureProjectRoadmapTaskSurface()` or `createImplementationTask()`.
+The package does not auto-convert nested human planning structures like `tasks` and `subtasks` into durable implementation-item tasks. To import a packet and immediately materialize a visible roadmap surface, use `importImplementationPacketAndMaterializeRoadmap()`. If you only need the task records, use `ensureProjectRoadmapTaskSurface()` or `createImplementationTask()`.
 
 A copyable example payload is packaged at `examples/implementation-plan-packet.minimal.json`.
 
@@ -587,6 +587,7 @@ Generated scripts are ephemeral helpers, not source-of-truth. The server keeps S
 | `getProjectImplementationRoadmapReport(projectId)` | Get the SQL-backed implementation roadmap report payload. |
 | `downloadProjectImplementationRoadmapReportMarkdown(projectId)` | Download the implementation roadmap markdown report. |
 | `ensureProjectRoadmapTaskSurface(projectId, { requestedBy, assignedTo, createAcceptanceSubtasks })` | Materialize the active roadmap item's parent task and acceptance subtasks. |
+| `importImplementationPacketAndMaterializeRoadmap(packetPayload, { importedBy, requestedBy, createdBy, workflowId, bindingRole, assignedTo, notes, createAcceptanceSubtasks })` | Import a governed implementation packet, bind it to the project workflow, and materialize the roadmap projection. |
 | `listProjectOpenTasks(projectId)` | Open tasks for a project. |
 | `getProjectPerformanceMetrics(projectId, { workflowId, workflowRunId, sinceUtc })` | Performance metrics. |
 
@@ -618,6 +619,7 @@ Current package version: `1.0.0-beta.13`.
 | `updateAcceptanceCheckStatus(itemId, checkId, body)` | Update acceptance check. |
 | `createImplementationPacketGateDecision(packetId, body)` | Record gate decision. |
 | `bindImplementationPacketToWorkflow(workflowId, body)` | Bind packet to workflow. |
+| `importImplementationPacketAndMaterializeRoadmap(packetPayload, { importedBy, requestedBy, createdBy, workflowId, bindingRole, assignedTo, notes, createAcceptanceSubtasks })` | Import, bind, materialize tasks, and read back roadmap counts in one call. |
 | `getWorkflowImplementationRoadmap(workflowId)` | Workflow-linked roadmap. |
 | `getWorkflowResumeContext(workflowId)` | Resume context. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.35",
+  "version": "1.1.36",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.35';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.36';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -114,6 +114,32 @@ function cleanText(value) {
   return text || null;
 }
 
+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}:`)));
+}
+
 function cleanList(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => cleanText(item)).filter(Boolean);
@@ -1626,6 +1652,100 @@ export class AIEngineClient {
     });
   }
 
+  async importImplementationPacketAndMaterializeRoadmap(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) || this.actorId;
+    const normalizedRequestedBy = cleanText(requestedBy) || normalizedImportedBy;
+    const normalizedCreatedBy = cleanText(createdBy) || normalizedRequestedBy;
+
+    const importedPacket = await this.importImplementationPacket({
+      ...packetPayload,
+      imported_by: normalizedImportedBy,
+    });
+    const projectReference = this._resolveImplementationPacketProjectReference(packetPayload);
+    if (!projectReference) {
+      throw new Error('Could not resolve a project reference from the packet payload.');
+    }
+    const projectPayload = await this.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 = this._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 this._resolveImplementationPacketWorkflowId(workflowReference);
+    const workflowSlug = cleanText(projectSummary.workflow_slug);
+    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 || packetId);
+
+    const binding = await this.bindImplementationPacketToWorkflow(resolvedWorkflowId, {
+      packet_id: packetId,
+      binding_role: cleanText(bindingRole) || 'active',
+      created_by: normalizedCreatedBy,
+      notes: cleanText(notes),
+    });
+
+    const taskSurface = await this.ensureProjectRoadmapTaskSurface(projectId, {
+      requestedBy: normalizedRequestedBy,
+      assignedTo,
+      createAcceptanceSubtasks,
+    });
+
+    const roadmapReport = await this.getProjectImplementationRoadmapReport(projectId);
+    const roadmapMarkdown = await this.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,
+      },
+    };
+  }
+
   async listProjectOpenTasks(projectId) {
     return this._request(`/api/operator/projects/${projectId}/open-tasks`);
   }
@@ -1636,6 +1756,52 @@ export class AIEngineClient {
     });
   }
 
+  _resolveImplementationPacketProjectReference(packetPayload) {
+    return 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);
+  }
+
+  async _resolveImplementationPacketWorkflowId(workflowReference) {
+    const normalized = cleanText(workflowReference);
+    if (!normalized) {
+      throw new Error('workflow reference is required.');
+    }
+    const workflow = await this.getWorkflow(normalized);
+    if (workflow) {
+      return cleanText(workflow.workflow_id) || cleanText(workflow.workflowId) || normalized;
+    }
+    const workflowList = await this.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}`);
+  }
+
   // ─── Implementation Tasks ──────────────────────────────────────────────────
 
   async createImplementationTask(implementationItemId, {