ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/workflow-manager.mjs

@@ -0,0 +1,745 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  applyWorkflowManagerArtifact,
+  applyWorkflowManagerRequirement,
+  applyWorkflowManagerTask,
+  applyWorkflowManagerTestCase,
+  inspectWorkflowManagerFacts,
+  recordWorkflowManagerTestRun,
+} from "./workflow-manager-facts.mjs";
+import {
+  inspectWorkflowManagerContracts,
+  renderWorkflowManagerActionHelp,
+  validateWorkflowManagerActionInput,
+  WORKFLOW_MANAGER_ACTION_NAMES,
+  WORKFLOW_MANAGER_CONTRACTS_SCHEMA_VERSION,
+} from "./workflow-manager-contracts.mjs";
+import {
+  appendPrototypeChangeRequestAttachment,
+  applyWorkflowManagerComponentCandidateTransition,
+  applyPrototypeChangeRequest,
+  applyWorkflowManagerPageReview,
+  applyWorkflowManagerVisualStandardReview,
+  createPrototypeChangeRequest,
+  discardPrototypeChangeRequest,
+  finalizePrototypeReviewBatch,
+  inspectWorkflowManagerPrototypeAttachment,
+  inspectWorkflowManagerPrototypes,
+  markPrototypeChangeRequestExecution,
+  planWorkflowManagerComponentCandidateTransition,
+  PrototypeTerminalScopeError,
+  PrototypeSourceSnapshotError,
+  inspectWorkflowManagerPrototypeSourceSnapshots,
+  resolveWorkflowManagerPrototypeContent,
+} from "./workflow-manager-prototypes.mjs";
+import {
+  applyWorkflowManagerInitializationScript,
+  applyWorkflowManagerSystemLifecycle,
+  inspectWorkflowManagerSystems,
+  planWorkflowManagerInitializationScript,
+  planWorkflowManagerSystemLifecycle,
+} from "./workflow-manager-systems.mjs";
+import {
+  applyWorkflowManagerMockSync,
+  inspectWorkflowManagerMock,
+  planWorkflowManagerMockSync,
+} from "./workflow-manager-mock.mjs";
+import {
+  applyWorkflowManagerGateDecision,
+  applyWorkflowManagerSettingsUpdate,
+  applyWorkflowManagerTransition,
+  decideWorkflowManagerRelationship,
+  inspectWorkflowManagerSettings,
+  invalidateWorkflowManagerRelationship,
+  planWorkflowManagerSettingsUpdate,
+  suggestWorkflowManagerRelationship,
+} from "./workflow-manager-governance.mjs";
+
+const runtimeRoot = path.dirname(fileURLToPath(import.meta.url));
+const installedStateRuntime = path.join(runtimeRoot, "..", "state", "delivery-state.mjs");
+const packageStateRuntime = path.join(runtimeRoot, "delivery-state.mjs");
+const stateRuntime = fs.existsSync(installedStateRuntime) ? installedStateRuntime : packageStateRuntime;
+const { executeDeliveryStateCommand } = await import(pathToFileURL(stateRuntime).href);
+const require = createRequire(import.meta.url);
+const installedYaml = path.join(runtimeRoot, "..", "state", "vendor", "yaml", "dist", "index.js");
+const yamlPackage = require(fs.existsSync(installedYaml) ? installedYaml : "yaml");
+const yaml = {
+  parse: yamlPackage.parse,
+  stringify: (value) => yamlPackage.stringify(value, { lineWidth: 0 }),
+};
+
+export const WORKFLOW_MANAGER_SCHEMA_VERSION = "workflow-manager.v1";
+export const WORKFLOW_MANAGER_PROTOTYPE = Object.freeze({
+  revision: "wm-prototype-r33",
+  checksum: "f98e7595",
+});
+
+export const WORKFLOW_MANAGER_RESOURCE_NAMES = Object.freeze([
+  "manager", "contracts", "facts", "prototypes", "prototype-source-snapshots", "attachments", "systems", "mock", "settings",
+]);
+const RESOURCE_NAMES = new Set(WORKFLOW_MANAGER_RESOURCE_NAMES);
+const ACTION_NAMES = new Set(WORKFLOW_MANAGER_ACTION_NAMES);
+
+export function renderWorkflowManagerHelp(options = {}) {
+  const command = options.command || "manager";
+  return [
+    `Workflow Manager contract: ${WORKFLOW_MANAGER_CONTRACTS_SCHEMA_VERSION}`,
+    "",
+    "Usage:",
+    `  ${command} inspect [workspace-directory]`,
+    `  ${command} <list|show|export> [workspace-directory] --resource <resource> [--terminal-id all|<terminal-id>]`,
+    `  ${command} action <action-name> [workspace-directory] --input <json-file>`,
+    `  ${command} action <action-name> --help`,
+    `  ${command} serve [workspace-directory] [--port <port>] [--no-open]`,
+    "",
+    "Resources:",
+    `  ${WORKFLOW_MANAGER_RESOURCE_NAMES.join(" ")}`,
+    "",
+    "Governed actions:",
+    ...WORKFLOW_MANAGER_ACTION_NAMES.map((action) => `  ${action}`),
+    "",
+    `Run '${command} action <action-name> --help' for authorization, concurrency, planning, idempotency, and input fields.`,
+  ].join("\n");
+}
+
+export function renderWorkflowManagerCommandHelp(action, options = {}) {
+  const command = options.command || "manager";
+  return action ? renderWorkflowManagerActionHelp(action, { command }) : renderWorkflowManagerHelp({ command });
+}
+
+export class WorkflowManagerError extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.name = "WorkflowManagerError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export const WORKFLOW_MANAGER_NODES = Object.freeze([
+  { node_id: "00-bootstrap", name: "项目上下文启动", phase: "entry" },
+  { node_id: "01-product-shaping", name: "产品塑形", phase: "design" },
+  { node_id: "02-solution-design", name: "方案设计", phase: "design" },
+  { node_id: "03-delivery-readiness", name: "交付准备", phase: "design" },
+  { node_id: "04-implementation", name: "开发实现", phase: "development" },
+  { node_id: "05-candidate-assurance", name: "候选版本保障", phase: "development" },
+  { node_id: "06-version-closeout", name: "版本收尾", phase: "development" },
+]);
+
+const MANAGER_PAGES = Object.freeze([
+  { page_id: "P01", name: "工作台", route: "/overview", availability: "available" },
+  { page_id: "P02", name: "开发流程", route: "/workflow", availability: "available" },
+  { page_id: "P19", name: "产品需求", route: "/product/requirements", availability: "available" },
+  { page_id: "P03", name: "执行任务", route: "/tasks", availability: "available" },
+  { page_id: "P18", name: "测试用例", route: "/test-cases", availability: "available" },
+  { page_id: "P04", name: "交付成果", route: "/artifacts", availability: "available" },
+  { page_id: "P06", name: "待办决策", route: "/decisions", availability: "available" },
+  { page_id: "P07", name: "项目原型", route: "/prototypes", availability: "available" },
+  { page_id: "P11", name: "项目视觉规范", route: "/prototypes/visual-standard", availability: "available" },
+  { page_id: "P12", name: "原型审批管理", route: "/prototypes/reviews", availability: "available" },
+  { page_id: "P13", name: "页面审核详情", route: "/prototypes/reviews/page", availability: "available", navigation: "contextual" },
+  { page_id: "P14", name: "页面路由管理", route: "/prototypes/routes", availability: "available" },
+  { page_id: "P15", name: "页面路由关系", route: "/prototypes/route-graph", availability: "available" },
+  { page_id: "P16", name: "修改要求", route: "/prototypes/change-requests", availability: "available" },
+  { page_id: "P17", name: "修订记录", route: "/prototypes/revisions", availability: "available" },
+  { page_id: "P08", name: "项目系统", route: "/systems", availability: "available" },
+  { page_id: "P09", name: "模拟服务", route: "/mock", availability: "available" },
+  { page_id: "P05", name: "操作与变更记录", route: "/events", availability: "available" },
+  { page_id: "P10", name: "设置", route: "/settings", availability: "available" },
+].map((page) => Object.freeze({
+  ...page,
+  lifecycle_status: page.availability,
+  mutability: "read-only",
+})));
+
+const PAGE_ROUTES = new Map(MANAGER_PAGES.map((page) => [page.page_id, page.route]));
+
+function workspaceIdentity(projectRoot) {
+  const configurationFile = path.join(projectRoot, ".workflow", "config", "workspace.yaml");
+  if (!fs.existsSync(configurationFile)) {
+    throw new Error(`Workflow Manager requires workspace configuration: ${configurationFile}`);
+  }
+  const configuration = yaml.parse(fs.readFileSync(configurationFile, "utf8"));
+  const workflowRepositoryPath = path.resolve(projectRoot, configuration.workflow_repository?.path || ".");
+  const codeRepositoryPath = configuration.code_repository?.path
+    ? path.resolve(projectRoot, configuration.code_repository.path)
+    : null;
+  return {
+    workspace_id: configuration.workspace_id,
+    repository_layout: configuration.repository_layout,
+    workflow_repository: {
+      path: configuration.workflow_repository?.path || ".",
+      branch: configuration.workflow_repository?.branch || null,
+      current_branch: repositoryBranch(workflowRepositoryPath),
+    },
+    code_repository: {
+      repo_id: configuration.code_repository?.repo_id || null,
+      path: configuration.code_repository?.path || null,
+      default_branch: configuration.code_repository?.default_branch || null,
+      current_branch: codeRepositoryPath ? repositoryBranch(codeRepositoryPath) : null,
+    },
+  };
+}
+
+function repositoryBranch(repositoryPath) {
+  const result = spawnSync("git", ["branch", "--show-current"], {
+    cwd: repositoryPath,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+
+function projectIdentity(inspection, projectRoot) {
+  const development = inspection.workflow_state?.development_state || {};
+  return {
+    project_id: inspection.project_id || inspection.project?.project_id || path.basename(projectRoot),
+    name: inspection.project?.name || inspection.project_id || path.basename(projectRoot),
+    iteration_id: development.scope_id || inspection.project?.current_iteration_id || null,
+    state_revision: development.revision ?? inspection.workflow_state?.revision ?? 0,
+  };
+}
+
+function countLabel(values) {
+  return `${Array.isArray(values) ? values.length : 0} 项`;
+}
+
+function stateFacts(derived) {
+  const tasks = Array.isArray(derived.task_facts) ? derived.task_facts : [];
+  const gates = Array.isArray(derived.gate_facts) ? derived.gate_facts : [];
+  const artifacts = Array.isArray(derived.artifact_facts) ? derived.artifact_facts : [];
+  const missing = Array.isArray(derived.missing_conditions) ? derived.missing_conditions : [];
+  const blocking = Array.isArray(derived.blocking_conditions) ? derived.blocking_conditions : [];
+  return [
+    { fact_id: "tasks", label: "任务事实", value: countLabel(tasks), source_page_id: "P03", records: tasks },
+    { fact_id: "gates", label: "人工审核点", value: countLabel(gates), source_page_id: "P06", records: gates },
+    { fact_id: "artifacts", label: "交付成果", value: countLabel(artifacts), source_page_id: "P04", records: artifacts },
+    { fact_id: "missing", label: "尚缺条件", value: countLabel(missing), source_page_id: "P02", records: missing },
+    { fact_id: "blocking", label: "阻断条件", value: countLabel(blocking), source_page_id: "P05", records: blocking },
+    {
+      fact_id: "receipt",
+      label: "运行凭证",
+      value: derived.completion_receipt_id || "尚未生成",
+      source_page_id: "P04",
+      records: derived.completion_receipt_id ? [derived.completion_receipt_id] : [],
+    },
+  ].map((fact) => ({
+    ...fact,
+    source_route: PAGE_ROUTES.get(fact.source_page_id),
+    mutability: "derived-read-only",
+  }));
+}
+
+function nodeProjection(definition, sequence, derivedStates, contracts) {
+  const derived = derivedStates?.[definition.node_id] || {};
+  const contract = contracts?.[definition.node_id] || {};
+  return {
+    ...definition,
+    sequence,
+    state: derived.state || "pending",
+    state_source: "derived_node_states",
+    missing_conditions: Array.isArray(derived.missing_conditions) ? derived.missing_conditions : [],
+    blocking_conditions: Array.isArray(derived.blocking_conditions) ? derived.blocking_conditions : [],
+    completion_receipt: derived.completion_receipt_id || derived.completion_receipt || null,
+    completion_ready: derived.completion_ready === true,
+    node_attempt: derived.node_attempt ?? 0,
+    mutability: "derived-read-only",
+    contract: {
+      prerequisites: Array.isArray(contract.prerequisites) ? contract.prerequisites : [],
+      internal_gates: Array.isArray(contract.internal_gates) ? contract.internal_gates : [],
+      completion: contract.completion || {},
+    },
+    state_facts: stateFacts(derived),
+  };
+}
+
+function workflowFocus(nodes) {
+  const priority = ["blocked", "active", "ready-to-complete", "waiting", "pending", "completed"];
+  return [...nodes].sort((left, right) => priority.indexOf(left.state) - priority.indexOf(right.state))[0] || null;
+}
+
+export function buildWorkflowManagerProjection(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const inspection = executeDeliveryStateCommand(["inspect", "--project", root], { yaml });
+  const nodes = WORKFLOW_MANAGER_NODES.map((definition, sequence) =>
+    nodeProjection(definition, sequence, inspection.derived_node_states, inspection.node_contracts));
+  const focusNode = workflowFocus(nodes);
+  return {
+    schema_version: WORKFLOW_MANAGER_SCHEMA_VERSION,
+    lifecycle_status: "active",
+    mutability: "read-only",
+    prototype: WORKFLOW_MANAGER_PROTOTYPE,
+    workspace: workspaceIdentity(root),
+    project: projectIdentity(inspection, root),
+    workflow: {
+      state_source: "state inspect.derived_node_states",
+      nodes,
+      focus_node_id: focusNode?.node_id || null,
+    },
+    workbench: {
+      focus_node_id: focusNode?.node_id || null,
+      attention: {
+        missing_conditions: focusNode?.missing_conditions.length || 0,
+        blocking_conditions: focusNode?.blocking_conditions.length || 0,
+        pending_gates: focusNode?.state_facts.find((fact) => fact.fact_id === "gates")?.records
+          .filter((gate) => !new Set(["approved", "not-required"]).has(gate.decision)).length || 0,
+      },
+      next_action: focusNode?.state === "completed"
+        ? "进入下一节点并核对其正式状态依据"
+        : focusNode?.completion_ready
+        ? "核对完成条件并执行合法节点转换"
+        : "处理当前节点尚缺条件和阻断项",
+    },
+    pages: MANAGER_PAGES,
+    facts: inspectWorkflowManagerFacts(root),
+  };
+}
+
+function withPrototypeResourceContext(projectRoot, resource) {
+  const root = path.resolve(projectRoot);
+  const inspection = executeDeliveryStateCommand(["inspect", "--project", root], { yaml });
+  const workspace = workspaceIdentity(root);
+  return {
+    ...resource,
+    context: {
+      project: projectIdentity(inspection, root),
+      workspace,
+      branch: workspace.workflow_repository.current_branch || workspace.workflow_repository.branch,
+      iteration_id: resource.iteration_id || null,
+      prototype_revision_id: resource.prototype_revision_id,
+      prototype_revision_checksum: resource.prototype_revision_checksum,
+      terminal_id: resource.terminal_scope?.terminal_id || null,
+    },
+  };
+}
+
+export async function queryWorkflowManagerResource(projectRoot, resource, options = {}) {
+  if (!RESOURCE_NAMES.has(resource)) {
+    throw new WorkflowManagerError("resource-not-found", `Unknown Workflow Manager resource: ${resource}`, 404);
+  }
+  if (resource === "manager") return buildWorkflowManagerProjection(projectRoot);
+  if (resource === "contracts") return inspectWorkflowManagerContracts();
+  if (resource === "facts") return inspectWorkflowManagerFacts(projectRoot);
+  if (resource === "prototypes") {
+    let projection;
+    try {
+      projection = inspectWorkflowManagerPrototypes(projectRoot, options);
+    } catch (error) {
+      if (error instanceof WorkflowManagerError) throw error;
+      if (error instanceof PrototypeTerminalScopeError) {
+        throw new WorkflowManagerError(error.code, error.message, 422);
+      }
+      throw new WorkflowManagerError("prototype-revision-invalid", error.message, 422);
+    }
+    return withPrototypeResourceContext(projectRoot, projection);
+  }
+  if (resource === "prototype-source-snapshots") {
+    let snapshots;
+    try {
+      snapshots = inspectWorkflowManagerPrototypeSourceSnapshots(projectRoot, options);
+    } catch (error) {
+      if (error instanceof WorkflowManagerError) throw error;
+      if (error instanceof PrototypeTerminalScopeError) {
+        throw new WorkflowManagerError(error.code, error.message, 422);
+      }
+      if (error instanceof PrototypeSourceSnapshotError) {
+        const status = error.code === "prototype-source-snapshot-not-registered" ? 404 : 422;
+        throw new WorkflowManagerError(error.code, error.message, status);
+      }
+      throw new WorkflowManagerError("prototype-revision-invalid", error.message, 422);
+    }
+    return withPrototypeResourceContext(projectRoot, snapshots);
+  }
+  if (resource === "attachments") return inspectWorkflowManagerPrototypeAttachment(projectRoot, {
+    attachment_id: options.attachmentId,
+    expected_checksum: options.expectedChecksum,
+  });
+  if (resource === "systems") return inspectWorkflowManagerSystems(projectRoot, options);
+  if (resource === "mock") return inspectWorkflowManagerMock(projectRoot, options);
+  return inspectWorkflowManagerSettings(projectRoot);
+}
+
+function executePrototypeManagerAction(operation) {
+  try {
+    return operation();
+  } catch (error) {
+    if (error instanceof PrototypeTerminalScopeError) {
+      throw new WorkflowManagerError(error.code, error.message, 422);
+    }
+    throw error;
+  }
+}
+
+export async function executeWorkflowManagerAction(projectRoot, action, input = {}, options = {}) {
+  if (!ACTION_NAMES.has(action)) {
+    throw new WorkflowManagerError("action-not-found", `Unknown Workflow Manager action: ${action}`, 404);
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new WorkflowManagerError("invalid-request", "Workflow Manager action input must be a JSON object", 400);
+  }
+  const validation = validateWorkflowManagerActionInput(action, input);
+  if (!validation.valid) {
+    throw new WorkflowManagerError("invalid-action-input", validation.message, 400);
+  }
+  if (action === "requirement-apply") return applyWorkflowManagerRequirement(projectRoot, input);
+  if (action === "task-apply") return applyWorkflowManagerTask(projectRoot, input, options);
+  if (action === "test-case-apply") return applyWorkflowManagerTestCase(projectRoot, input);
+  if (action === "test-run-record") return recordWorkflowManagerTestRun(projectRoot, input);
+  if (action === "artifact-register") return applyWorkflowManagerArtifact(projectRoot, input, options);
+  if (action === "prototype-change-request-create") {
+    return executePrototypeManagerAction(() => createPrototypeChangeRequest(projectRoot, input));
+  }
+  if (action === "prototype-change-request-edit") {
+    return executePrototypeManagerAction(() => applyPrototypeChangeRequest(projectRoot, input.change_request_id, input));
+  }
+  if (action === "prototype-change-request-attachment-add") {
+    return executePrototypeManagerAction(() => appendPrototypeChangeRequestAttachment(projectRoot, input.change_request_id, input));
+  }
+  if (action === "prototype-review-batch-finalize") {
+    return executePrototypeManagerAction(() => finalizePrototypeReviewBatch(projectRoot, input));
+  }
+  if (action === "prototype-page-review-apply") {
+    return executePrototypeManagerAction(() => applyWorkflowManagerPageReview(projectRoot, input, options));
+  }
+  if (action === "prototype-visual-standard-review-apply") {
+    return executePrototypeManagerAction(() => applyWorkflowManagerVisualStandardReview(projectRoot, input, options));
+  }
+  if (action === "prototype-component-candidate-transition-plan") {
+    return executePrototypeManagerAction(() => planWorkflowManagerComponentCandidateTransition(projectRoot, input));
+  }
+  if (action === "prototype-component-candidate-transition-apply") {
+    return executePrototypeManagerAction(() => applyWorkflowManagerComponentCandidateTransition(projectRoot, input, options));
+  }
+  if (action === "prototype-change-request-execution-start") {
+    return executePrototypeManagerAction(() => markPrototypeChangeRequestExecution(projectRoot, input.change_request_id, input));
+  }
+  if (action === "prototype-change-request-discard") {
+    return executePrototypeManagerAction(() => discardPrototypeChangeRequest(projectRoot, input.change_request_id, input));
+  }
+  if (action === "system-initialization-script-plan") {
+    return planWorkflowManagerInitializationScript(projectRoot, input.system_id, input);
+  }
+  if (action === "system-initialization-script-apply") {
+    return applyWorkflowManagerInitializationScript(projectRoot, input.system_id, input, options);
+  }
+  if (action === "system-lifecycle-plan") {
+    return planWorkflowManagerSystemLifecycle(projectRoot, input.system_id, input);
+  }
+  if (action === "system-lifecycle-apply") {
+    return applyWorkflowManagerSystemLifecycle(projectRoot, input.system_id, input, options);
+  }
+  if (action === "mock-sync-plan") return planWorkflowManagerMockSync(projectRoot, input, options);
+  if (action === "mock-sync-apply") return applyWorkflowManagerMockSync(projectRoot, input, options);
+  if (action === "gate-decision-apply") return applyWorkflowManagerGateDecision(projectRoot, input, options);
+  if (action === "workflow-transition-apply") return applyWorkflowManagerTransition(projectRoot, input, options);
+  if (action === "relationship-suggest") return suggestWorkflowManagerRelationship(projectRoot, input, options);
+  if (action === "relationship-decide") return decideWorkflowManagerRelationship(projectRoot, input, options);
+  if (action === "relationship-invalidate") return invalidateWorkflowManagerRelationship(projectRoot, input, options);
+  if (action === "settings-update-plan") return planWorkflowManagerSettingsUpdate(projectRoot, input);
+  return applyWorkflowManagerSettingsUpdate(projectRoot, input, options);
+}
+
+function sendJson(response, status, value) {
+  const body = `${JSON.stringify(value)}\n`;
+  response.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(body),
+    "X-Content-Type-Options": "nosniff",
+  });
+  response.end(body);
+}
+
+function sendError(response, error) {
+  const status = Number.isInteger(error?.status) ? error.status : 400;
+  sendJson(response, status, {
+    error: {
+      code: typeof error?.code === "string" ? error.code : "invalid-request",
+      message: error?.message || "Workflow Manager request failed",
+    },
+  });
+}
+
+function readJsonBody(request, maxBodyBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let length = 0;
+    let settled = false;
+    request.on("data", (chunk) => {
+      length += chunk.length;
+      if (length > maxBodyBytes) {
+        if (!settled) {
+          settled = true;
+          reject(new WorkflowManagerError("request-too-large", `Request body exceeds ${maxBodyBytes} bytes`, 413));
+        }
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => {
+      if (settled) return;
+      settled = true;
+      if (!length) return resolve({});
+      try {
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          throw new Error("JSON object required");
+        }
+        resolve(value);
+      } catch (error) {
+        reject(new WorkflowManagerError("invalid-json", `Invalid JSON request body: ${error.message}`, 400));
+      }
+    });
+    request.on("error", (error) => {
+      if (!settled) reject(error);
+    });
+  });
+}
+
+const SESSION_COOKIE = "workflow_manager_session";
+
+function safeEqual(left, right) {
+  const leftBytes = Buffer.from(String(left || ""));
+  const rightBytes = Buffer.from(String(right || ""));
+  return leftBytes.length === rightBytes.length && crypto.timingSafeEqual(leftBytes, rightBytes);
+}
+
+function cookieValue(request, name) {
+  for (const part of String(request.headers.cookie || "").split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 0 || part.slice(0, separator).trim() !== name) continue;
+    return decodeURIComponent(part.slice(separator + 1).trim());
+  }
+  return null;
+}
+
+function requestOrigin(request) {
+  const host = String(request.headers.host || "");
+  if (!host) throw new WorkflowManagerError("host-rejected", "Workflow Manager request Host is required", 403);
+  let parsed;
+  try { parsed = new URL(`http://${host}`); } catch {
+    throw new WorkflowManagerError("host-rejected", "Workflow Manager request Host is invalid", 403);
+  }
+  if (!new Set(["127.0.0.1", "localhost", "[::1]"]).has(parsed.hostname)) {
+    throw new WorkflowManagerError("host-rejected", "Workflow Manager accepts only loopback Host values", 403);
+  }
+  return parsed.origin;
+}
+
+function requireBrowserWriteSession(request, sessionToken) {
+  const origin = requestOrigin(request);
+  if (String(request.headers.origin || "") !== origin) {
+    throw new WorkflowManagerError("origin-rejected", "Workflow Manager write requires an exact same-origin request", 403);
+  }
+  if (!safeEqual(cookieValue(request, SESSION_COOKIE), sessionToken)) {
+    throw new WorkflowManagerError("session-required", "Workflow Manager write requires its current browser session", 401);
+  }
+}
+
+function publicDirectory(packageRoot, options) {
+  if (options.publicRoot) return path.resolve(options.publicRoot);
+  const installedPublic = path.join(runtimeRoot, "public");
+  if (fs.existsSync(installedPublic)) return installedPublic;
+  return path.join(path.resolve(packageRoot), "lib", "workflow-manager-public");
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function serveStatic(publicRoot, response, pathname) {
+  const requested = pathname === "/" ? "index.html" : pathname.slice(1);
+  const candidate = path.resolve(publicRoot, requested);
+  const fallback = path.join(publicRoot, "index.html");
+  const file = isInside(candidate, publicRoot) && fs.existsSync(candidate) && fs.statSync(candidate).isFile()
+    ? candidate
+    : fallback;
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    sendJson(response, 404, { error: "Workflow Manager frontend is not built." });
+    return;
+  }
+  const types = {
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".svg": "image/svg+xml",
+  };
+  const body = fs.readFileSync(file);
+  response.writeHead(200, {
+    "Content-Type": types[path.extname(file)] || "application/octet-stream",
+    "Content-Length": body.length,
+    "Cache-Control": "no-cache",
+    "Content-Security-Policy": "default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+  });
+  response.end(body);
+}
+
+function servePrototypeContent(root, response, relative, options = {}) {
+  const resolved = resolveWorkflowManagerPrototypeContent(root, relative, options);
+  const types = {
+    ".css": "text/css; charset=utf-8", ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8", ".json": "application/json; charset=utf-8",
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+  };
+  const body = fs.readFileSync(resolved.file);
+  response.writeHead(200, {
+    "Content-Type": types[path.extname(resolved.file).toLowerCase()] || "application/octet-stream",
+    "Content-Length": body.length,
+    "Cache-Control": "no-store",
+    "Content-Security-Policy": "default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'none'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cross-Origin-Resource-Policy": "same-origin",
+  });
+  response.end(body);
+}
+
+export function createWorkflowManagerServer(packageRoot, projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const publicRoot = publicDirectory(packageRoot, options);
+  const maxBodyBytes = options.maxBodyBytes || 12 * 1024 * 1024;
+  const sessionToken = options.sessionToken || crypto.randomBytes(32).toString("base64url");
+  const server = http.createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url || "/", "http://localhost");
+      if (request.method === "GET" && url.pathname === "/" && url.searchParams.has("session")) {
+        if (!safeEqual(url.searchParams.get("session"), sessionToken)) {
+          throw new WorkflowManagerError("session-invalid", "Workflow Manager browser session is invalid", 401);
+        }
+        response.writeHead(303, {
+          Location: "/",
+          "Set-Cookie": `${SESSION_COOKIE}=${encodeURIComponent(sessionToken)}; Path=/; HttpOnly; SameSite=Strict`,
+          "Cache-Control": "no-store",
+          "Referrer-Policy": "no-referrer",
+        });
+        response.end();
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/api/v1/health") {
+        sendJson(response, 200, { ok: true, schema_version: WORKFLOW_MANAGER_SCHEMA_VERSION });
+        return;
+      }
+      if (request.method === "GET" && url.pathname === "/api/v1/manager") {
+        sendJson(response, 200, buildWorkflowManagerProjection(root));
+        return;
+      }
+      if (request.method === "GET" && url.pathname.startsWith("/api/v1/prototype-content/")) {
+        const relative = decodeURIComponent(url.pathname.slice("/api/v1/prototype-content/".length));
+        servePrototypeContent(root, response, relative, {
+          revision: url.searchParams.get("revision") || undefined,
+          expectedChecksum: url.searchParams.get("expected_checksum") || undefined,
+        });
+        return;
+      }
+      if (request.method === "GET" && url.pathname.startsWith("/api/v1/prototype-source-snapshots/")) {
+        const sourceSnapshotId = decodeURIComponent(
+          url.pathname.slice("/api/v1/prototype-source-snapshots/".length),
+        );
+        sendJson(response, 200, await queryWorkflowManagerResource(root, "prototype-source-snapshots", {
+          experience: url.searchParams.get("experience") || undefined,
+          revision: url.searchParams.get("revision") || undefined,
+          expectedChecksum: url.searchParams.get("expected_checksum") || undefined,
+          terminalId: url.searchParams.get("terminal_id") || undefined,
+          pageId: url.searchParams.get("page_id") || undefined,
+          reviewSceneId: url.searchParams.get("review_scene_id") || undefined,
+          sourceRef: url.searchParams.get("source_ref") || undefined,
+          sourceSnapshotId,
+        }));
+        return;
+      }
+      const resourceMatch = request.method === "GET" && url.pathname.match(/^\/api\/v1\/resources\/([^/]+)$/);
+      if (resourceMatch) {
+        sendJson(response, 200, await queryWorkflowManagerResource(root, decodeURIComponent(resourceMatch[1]), {
+          experience: url.searchParams.get("experience") || undefined,
+          revision: url.searchParams.get("revision") || undefined,
+          branch: url.searchParams.get("branch") || undefined,
+          attachmentId: url.searchParams.get("attachment_id") || undefined,
+          expectedChecksum: url.searchParams.get("expected_checksum") || undefined,
+          terminalId: url.searchParams.get("terminal_id") || undefined,
+          pageId: url.searchParams.get("page_id") || undefined,
+          reviewSceneId: url.searchParams.get("review_scene_id") || undefined,
+          sourceSnapshotId: url.searchParams.get("source_snapshot_id") || undefined,
+          sourceRef: url.searchParams.get("source_ref") || undefined,
+        }));
+        return;
+      }
+      const actionMatch = request.method === "POST" && url.pathname.match(/^\/api\/v1\/actions\/([^/]+)$/);
+      if (actionMatch) {
+        const action = decodeURIComponent(actionMatch[1]);
+        if (!ACTION_NAMES.has(action)) {
+          throw new WorkflowManagerError("action-not-found", `Unknown Workflow Manager action: ${action}`, 404);
+        }
+        requireBrowserWriteSession(request, sessionToken);
+        const input = { ...(await readJsonBody(request, maxBodyBytes)), actor: options.uiActor || "human:workflow-manager-user" };
+        sendJson(response, 200, await executeWorkflowManagerAction(root, action, input, options));
+        return;
+      }
+      if (url.pathname.startsWith("/api/")) {
+        if (!new Set(["GET", "POST"]).has(request.method || "")) {
+          throw new WorkflowManagerError("method-not-allowed", "Method not allowed", 405);
+        }
+        throw new WorkflowManagerError("endpoint-not-found", `Unknown Workflow Manager endpoint: ${url.pathname}`, 404);
+      }
+      if (request.method !== "GET") throw new WorkflowManagerError("method-not-allowed", "Method not allowed", 405);
+      serveStatic(publicRoot, response, url.pathname);
+    } catch (error) {
+      sendError(response, error);
+    }
+  });
+  Object.defineProperty(server, "workflowManagerSessionToken", { value: sessionToken, enumerable: false });
+  return server;
+}
+
+function openBrowser(url) {
+  const command = process.platform === "win32"
+    ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin"
+      ? ["open", [url]]
+      : ["xdg-open", [url]];
+  try {
+    spawn(command[0], command[1], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    }).unref();
+  } catch {
+    // The returned loopback URL remains usable without a desktop opener.
+  }
+}
+
+export async function runWorkflowManagerCommand(packageRoot, projectRoot, action, options = {}) {
+  if (action === "inspect") return buildWorkflowManagerProjection(projectRoot);
+  if (new Set(["list", "show", "export"]).has(action)) {
+    if (!options.resource) throw new WorkflowManagerError("resource-required", `${action} requires --resource`, 400);
+    return queryWorkflowManagerResource(projectRoot, options.resource, options);
+  }
+  if (action === "action") {
+    if (!options.actionName) throw new WorkflowManagerError("action-required", "manager action requires an action name", 400);
+    return executeWorkflowManagerAction(projectRoot, options.actionName, options.input || {}, options);
+  }
+  if (action !== "serve") throw new Error("manager requires action inspect or serve.");
+  const port = Number(options.port || 4180);
+  if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 80) {
+    throw new Error("Workflow Manager port must be an integer from 1 to 65535 and cannot be 80.");
+  }
+  const host = "127.0.0.1";
+  const server = createWorkflowManagerServer(packageRoot, projectRoot, options);
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  const url = `http://${host}:${address.port}/?session=${encodeURIComponent(server.workflowManagerSessionToken)}`;
+  if (options.open !== false) (options.browserOpener || openBrowser)(url);
+  return { server, report: { action: "serve", url, project_root: path.resolve(projectRoot) } };
+}