ai-delivery-workflow 0.3.0 → 0.5.0

package/lib/npm-auth.mjs

@@ -0,0 +1,16 @@
+const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+const OFFICIAL_NPM_TOKEN_ENV_KEY = "npm_config_//registry.npmjs.org/:_authToken";
+
+export function withNpmAccessToken(environment = process.env) {
+  const token = typeof environment.NPM_ACCESS_TOKEN === "string"
+    ? environment.NPM_ACCESS_TOKEN.trim()
+    : "";
+  if (!token) return environment;
+
+  return {
+    ...environment,
+    [OFFICIAL_NPM_TOKEN_ENV_KEY]: token,
+  };
+}
+
+export { OFFICIAL_NPM_REGISTRY, OFFICIAL_NPM_TOKEN_ENV_KEY };

package/lib/npm-package-result.mjs

@@ -0,0 +1,11 @@
+export function normalizeNpmPackageResult(parsed, manifest) {
+  if (Array.isArray(parsed)) return parsed[0];
+  if (!parsed || typeof parsed !== "object") return parsed;
+  if (parsed.name || parsed.id || Array.isArray(parsed.files)) return parsed;
+
+  const direct = parsed[manifest.name];
+  if (direct && typeof direct === "object") return direct;
+
+  return Object.values(parsed).find((value) => value && typeof value === "object"
+    && (value.name === manifest.name || value.id === `${manifest.name}@${manifest.version}`));
+}

package/lib/png-evidence.mjs

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import zlib from "node:zlib";
+
+const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+function crc32(value) {
+  let checksum = 0xffffffff;
+  for (const byte of value) {
+    checksum ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      checksum = (checksum >>> 1) ^ (0xedb88320 & -(checksum & 1));
+    }
+  }
+  return (checksum ^ 0xffffffff) >>> 0;
+}
+
+function paeth(left, above, upperLeft) {
+  const estimate = left + above - upperLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const aboveDistance = Math.abs(estimate - above);
+  const upperLeftDistance = Math.abs(estimate - upperLeft);
+  if (leftDistance <= aboveDistance && leftDistance <= upperLeftDistance) return left;
+  return aboveDistance <= upperLeftDistance ? above : upperLeft;
+}
+
+function decodePng(file, expectedWidth, expectedHeight, label) {
+  const bytes = fs.readFileSync(file);
+  if (bytes.length < pngSignature.length || !bytes.subarray(0, 8).equals(pngSignature)) {
+    throw new Error(`${label} is not a PNG image.`);
+  }
+  let offset = 8;
+  let header = null;
+  let ended = false;
+  const compressed = [];
+  while (offset < bytes.length) {
+    if (offset + 12 > bytes.length) throw new Error(`${label} PNG chunk is truncated.`);
+    const length = bytes.readUInt32BE(offset);
+    const end = offset + 12 + length;
+    if (end > bytes.length) throw new Error(`${label} PNG chunk length is invalid.`);
+    const type = bytes.subarray(offset + 4, offset + 8);
+    const data = bytes.subarray(offset + 8, offset + 8 + length);
+    const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+    if (crc32(Buffer.concat([type, data])) !== expectedCrc) {
+      throw new Error(`${label} PNG chunk checksum mismatch.`);
+    }
+    const name = type.toString("ascii");
+    if (name === "IHDR") {
+      if (header || length !== 13) throw new Error(`${label} PNG header is invalid.`);
+      header = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (name === "IDAT") {
+      compressed.push(data);
+    } else if (name === "IEND") {
+      if (length !== 0) throw new Error(`${label} PNG end chunk is invalid.`);
+      ended = true;
+      offset = end;
+      break;
+    }
+    offset = end;
+  }
+  if (!header || !ended || offset !== bytes.length || compressed.length === 0) {
+    throw new Error(`${label} PNG structure is incomplete.`);
+  }
+  if (header.width !== expectedWidth || header.height !== expectedHeight) {
+    throw new Error(
+      `${label} PNG dimensions ${header.width}x${header.height} do not match ${expectedWidth}x${expectedHeight}.`,
+    );
+  }
+  if (header.bitDepth !== 8 || !new Set([2, 6]).has(header.colorType)
+      || header.compression !== 0 || header.filter !== 0 || header.interlace !== 0) {
+    throw new Error(`${label} PNG must be non-interlaced 8-bit RGB or RGBA.`);
+  }
+  const channels = header.colorType === 6 ? 4 : 3;
+  const stride = header.width * channels;
+  const expectedLength = (stride + 1) * header.height;
+  let scanlines;
+  try {
+    scanlines = zlib.inflateSync(Buffer.concat(compressed), { maxOutputLength: expectedLength });
+  } catch (error) {
+    throw new Error(`${label} PNG pixel data is invalid: ${error.message}`);
+  }
+  if (scanlines.length !== expectedLength) throw new Error(`${label} PNG pixel data length is invalid.`);
+  const decoded = Buffer.alloc(stride * header.height);
+  for (let y = 0; y < header.height; y += 1) {
+    const encodedRow = y * (stride + 1);
+    const decodedRow = y * stride;
+    const filter = scanlines[encodedRow];
+    if (filter > 4) throw new Error(`${label} PNG uses an invalid scanline filter.`);
+    for (let x = 0; x < stride; x += 1) {
+      const raw = scanlines[encodedRow + 1 + x];
+      const left = x >= channels ? decoded[decodedRow + x - channels] : 0;
+      const above = y > 0 ? decoded[decodedRow + x - stride] : 0;
+      const upperLeft = y > 0 && x >= channels
+        ? decoded[decodedRow + x - stride - channels]
+        : 0;
+      let value = raw;
+      if (filter === 1) value += left;
+      else if (filter === 2) value += above;
+      else if (filter === 3) value += Math.floor((left + above) / 2);
+      else if (filter === 4) value += paeth(left, above, upperLeft);
+      decoded[decodedRow + x] = value & 0xff;
+    }
+  }
+  if (channels === 4) return decoded;
+  const rgba = Buffer.alloc(header.width * header.height * 4);
+  for (let source = 0, target = 0; source < decoded.length; source += 3, target += 4) {
+    rgba[target] = decoded[source];
+    rgba[target + 1] = decoded[source + 1];
+    rgba[target + 2] = decoded[source + 2];
+    rgba[target + 3] = 255;
+  }
+  return rgba;
+}
+
+export function verifyVisualPngEvidence(files, viewport, label) {
+  const prototype = decodePng(
+    files.prototype,
+    viewport.width,
+    viewport.height,
+    `${label} Prototype screenshot`,
+  );
+  const candidate = decodePng(
+    files.candidate,
+    viewport.width,
+    viewport.height,
+    `${label} Candidate screenshot`,
+  );
+  const diff = decodePng(files.diff, viewport.width, viewport.height, `${label} Visual diff`);
+  let changedPixels = 0;
+  for (let offset = 0; offset < prototype.length; offset += 4) {
+    const changed = prototype[offset] !== candidate[offset]
+      || prototype[offset + 1] !== candidate[offset + 1]
+      || prototype[offset + 2] !== candidate[offset + 2]
+      || prototype[offset + 3] !== candidate[offset + 3];
+    const marked = diff[offset + 3] > 0;
+    if (changed !== marked) {
+      throw new Error(`${label} Visual diff PNG does not mark the independently measured pixels.`);
+    }
+    if (changed) changedPixels += 1;
+  }
+  return { changedPixels, totalPixels: viewport.width * viewport.height };
+}

package/lib/project-bootstrap.mjs

@@ -3,7 +3,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
-import { executeDeliveryStateCommand } from "./delivery-state.mjs";
+import {
+  findIncompatibleNodeStates,
+  stableValue,
+  withFormalStateReadLock,
+} from "./delivery-state.mjs";
 import { inspectGitRepository, readWorkspaceConfiguration } from "./workspace.mjs";
 
 const IGNORED_DIRECTORIES = new Set([
@@ -79,6 +83,8 @@ const WORKFLOW_REQUIRED_FILES = [
   ".codex/config.toml",
   "AGENTS.md",
   ".workflow/tools/state/state.mjs",
+  ".workflow/tools/state/history-anchor.mjs",
+  ".workflow/tools/state/fs-utils.mjs",
   ".workflow/tools/evolution/evolve.mjs",
   ".workflow/tools/hooks/hook-event.mjs",
   ".workflow/delivery/project.yaml",
@@ -289,18 +295,40 @@ function readStructuredFile(file, format, errors) {
   }
 }
 
+function normalizeInspectedScope(value, fallbackScopeId = null) {
+  return {
+    scope_id: value?.scope_id ?? fallbackScopeId,
+    active_nodes: Array.isArray(value?.active_nodes) ? value.active_nodes : [],
+    blocked_nodes: Array.isArray(value?.blocked_nodes) ? value.blocked_nodes : [],
+    completed_nodes: Array.isArray(value?.completed_nodes) ? value.completed_nodes : [],
+    pending_gates: Array.isArray(value?.pending_gates) ? value.pending_gates : [],
+  };
+}
+
+function inspectWorkflowScopes(workflowState, errors) {
+  const schemaVersion = Number(workflowState?.schema_version || 1);
+  const development = schemaVersion >= 2
+    ? normalizeInspectedScope(workflowState.development_state)
+    : normalizeInspectedScope(workflowState, workflowState.iteration_id ?? null);
+  const release = schemaVersion >= 2
+    ? normalizeInspectedScope(workflowState.release_state)
+    : normalizeInspectedScope(null);
+
+  for (const [scopeName, scope] of [["development", development], ["release", release]]) {
+    for (const conflict of findIncompatibleNodeStates(scope)) {
+      errors.push(`Workflow node appears in incompatible states in ${scopeName}: ${conflict.node} (${conflict.states.join(", ")}).`);
+    }
+  }
+
+  return { development, release };
+}
+
 function compareTasks(left, right) {
   const leftSequence = Number.isInteger(left.sequence) ? left.sequence : Number.MAX_SAFE_INTEGER;
   const rightSequence = Number.isInteger(right.sequence) ? right.sequence : Number.MAX_SAFE_INTEGER;
   return leftSequence - rightSequence || String(left.task_id).localeCompare(String(right.task_id));
 }
 
-function stableValue(value) {
-  if (Array.isArray(value)) return value.map(stableValue);
-  if (!value || typeof value !== "object") return value;
-  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
-}
-
 function taskStateChecksum(task, root) {
   const comparable = { ...task };
   const stateRoot = path.resolve(root, comparable.state_root || ".");
@@ -365,8 +393,14 @@ function inspectRuntime(root, errors, workflowRoot = ".workflow") {
     }
     return true;
   });
+  const readyIds = new Set(ready.map((task) => task.task_id));
+  const waiting = queued.filter((task) => !readyIds.has(task.task_id));
   const active = tasks.filter((task) => ACTIVE_TASK_STATUSES.has(task.status));
-  const recommended = [...active, ...ready].sort(compareTasks)[0] || null;
+  const retryable = tasks.filter((task) => task.status === "failed");
+  const recommended = active.sort(compareTasks)[0]
+    || retryable.sort(compareTasks)[0]
+    || ready.sort(compareTasks)[0]
+    || null;
   const checkpointRoot = path.join(root, workflowRoot, "control", "checkpoints");
   let sharedCheckpointCount = 0;
   const countCheckpoints = (directory) => {
@@ -381,9 +415,16 @@ function inspectRuntime(root, errors, workflowRoot = ".workflow") {
   return {
     task_count: tasks.length,
     closed_task_count: tasks.filter((task) => CLOSED_TASK_STATUSES.has(task.status)).length,
+    completed_task_count: tasks.filter((task) => task.status === "completed").length,
+    failed_task_count: tasks.filter((task) => task.status === "failed").length,
+    abandoned_task_count: tasks.filter((task) => task.status === "abandoned").length,
+    blocked_task_count: tasks.filter((task) => task.status === "blocked").length,
+    waiting_task_count: waiting.length,
     active_task_ids: active.map((task) => task.task_id),
+    retryable_task_ids: retryable.map((task) => task.task_id),
     queued_task_ids: queued.map((task) => task.task_id),
     ready_task_ids: ready.map((task) => task.task_id),
+    waiting_task_ids: waiting.map((task) => task.task_id),
     recommended_task_id: recommended?.task_id || null,
     recommended_iteration_id: recommended?.iteration_id || null,
     recommended_status: recommended?.status || null,
@@ -422,11 +463,16 @@ function recommendationFor(state, workflow, runtime) {
   if (state === "workflow-interrupted" || runtime.recommended_task_id) {
     const awaitingUser = runtime.next_action_owner === "user";
     const awaitingExternal = runtime.next_action_owner === "external";
+    const retryCommand = runtime.recommended_status === "failed"
+      ? `task-state.mjs activate --task-id ${runtime.recommended_task_id} --new-attempt --phase repair`
+      : null;
     return {
       skill: "ai-delivery-checkpoint-task",
       action: awaitingUser || awaitingExternal
         ? runtime.next_action
-        : `恢复并核对任务 ${runtime.recommended_task_id || "unknown"}，只继续其幂等 next_action。`,
+        : retryCommand
+          ? `使用 ${retryCommand} 重试失败的逻辑任务，然后只继续其幂等 next_action。`
+          : `恢复并核对任务 ${runtime.recommended_task_id || "unknown"}，只继续其幂等 next_action。`,
       requires_user_input: awaitingUser,
       mutation_allowed: !awaitingUser && !awaitingExternal,
     };
@@ -484,17 +530,28 @@ export function inspectProjectState(target) {
   const workflow = {
     project_id: null,
     iteration_id: null,
+    release_id: null,
     artifact_count: 0,
     delivery_artifact_count: 0,
     active_nodes: [],
     blocked_nodes: [],
     pending_gates: [],
+    development_state: normalizeInspectedScope(null),
+    release_state: normalizeInspectedScope(null),
   };
   let runtime = {
     task_count: 0,
+    closed_task_count: 0,
+    completed_task_count: 0,
+    failed_task_count: 0,
+    abandoned_task_count: 0,
+    blocked_task_count: 0,
+    waiting_task_count: 0,
     active_task_ids: [],
+    retryable_task_ids: [],
     queued_task_ids: [],
     ready_task_ids: [],
+    waiting_task_ids: [],
     recommended_task_id: null,
     dependency_errors: [],
   };
@@ -518,9 +575,22 @@ export function inspectProjectState(target) {
       legacyLayout ? ".ai-delivery/install-manifest.json" : ".workflow/config/install-manifest.json",
     ), "json", errors);
     const stateRoot = path.join(root, workflowRoot);
-    const project = readStructuredFile(path.join(stateRoot, "delivery", "project.yaml"), "yaml", errors);
-    const workflowState = readStructuredFile(path.join(stateRoot, "delivery", "workflow-state.yaml"), "yaml", errors);
-    const registry = readStructuredFile(path.join(stateRoot, "delivery", "artifact-registry.yaml"), "yaml", errors);
+    let project = null;
+    let workflowState = null;
+    let registry = null;
+    const readFormalState = () => {
+      project = readStructuredFile(path.join(stateRoot, "delivery", "project.yaml"), "yaml", errors);
+      workflowState = readStructuredFile(path.join(stateRoot, "delivery", "workflow-state.yaml"), "yaml", errors);
+      registry = readStructuredFile(path.join(stateRoot, "delivery", "artifact-registry.yaml"), "yaml", errors);
+    };
+    if (legacyLayout) readFormalState();
+    else {
+      try {
+        withFormalStateReadLock(root, readFormalState);
+      } catch (error) {
+        errors.push(error.message);
+      }
+    }
     readStructuredFile(path.join(stateRoot, "delivery", "standards-baseline.yaml"), "yaml", errors);
     readStructuredFile(path.join(stateRoot, "standards", "index.yaml"), "yaml", errors);
     if (manifest) {
@@ -532,11 +602,15 @@ export function inspectProjectState(target) {
       if (!installedSkills.length) errors.push("安装清单未登记任何 skill");
     }
     if (project && workflowState) {
+      const scopes = inspectWorkflowScopes(workflowState, errors);
       workflow.project_id = project.project_id || null;
-      workflow.iteration_id = workflowState.iteration_id || project.current_iteration_id || null;
-      workflow.active_nodes = Array.isArray(workflowState.active_nodes) ? workflowState.active_nodes : [];
-      workflow.blocked_nodes = Array.isArray(workflowState.blocked_nodes) ? workflowState.blocked_nodes : [];
-      workflow.pending_gates = Array.isArray(workflowState.pending_gates) ? workflowState.pending_gates : [];
+      workflow.iteration_id = scopes.development.scope_id || project.current_iteration_id || null;
+      workflow.release_id = scopes.release.scope_id || project.current_release_id || null;
+      workflow.active_nodes = scopes.development.active_nodes;
+      workflow.blocked_nodes = scopes.development.blocked_nodes;
+      workflow.pending_gates = scopes.development.pending_gates;
+      workflow.development_state = scopes.development;
+      workflow.release_state = scopes.release;
       if (project.project_id !== workflowState.project_id) {
         errors.push(`${workflowRoot}/delivery/project.yaml 与 workflow-state.yaml 的 project_id 不一致`);
       }
@@ -655,16 +729,11 @@ function taskPlanFor(initialState, result) {
 
 function adoptionMarkdown(initialState, scan, result) {
   const gaps = [];
-  let artifactTypes = [];
-  try {
-    const registry = parseYaml(fs.readFileSync(
+  const registry = withFormalStateReadLock(result.project_root, () => parseYaml(fs.readFileSync(
       path.join(result.project_root, ".workflow", "delivery", "artifact-registry.yaml"),
       "utf8",
-    ));
-    artifactTypes = (registry?.artifacts || []).map((artifact) => artifact.artifact_type || "");
-  } catch {
-    artifactTypes = [];
-  }
+    )));
+  const artifactTypes = (registry?.artifacts || []).map((artifact) => artifact.artifact_type || "");
   if (!artifactTypes.some((type) => /product.*baseline/.test(type))) gaps.push("缺少经确认的产品基线。");
   if (!artifactTypes.some((type) => /architecture.*baseline/.test(type))) gaps.push("缺少经确认的架构基线。");
   if (scan.summary.has_code && !scan.summary.categories.test) gaps.push("未发现可识别的自动化测试文件，需人工核对测试入口。");
@@ -694,26 +763,6 @@ ${result.recommendation.action}
 `;
 }
 
-function registerBootstrapReport(root, entry) {
-  const yaml = {
-    parse: parseYaml,
-    stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
-  };
-  const inspected = executeDeliveryStateCommand(["inspect", "--project", root], { yaml });
-  executeDeliveryStateCommand([
-    "artifact", "register",
-    "--project", root,
-    "--expected-revision", String(inspected.artifact_registry.revision),
-    "--id", entry.artifact_id,
-    "--artifact-type", entry.artifact_type,
-    "--path", entry.path,
-    "--node", "00-bootstrap",
-    "--status", entry.status,
-    "--version", String(entry.version),
-    "--producer-skill", entry.producer_skill,
-  ], { yaml });
-}
-
 function writeBootstrapArtifacts(root, initialState, result, sourceScan = null) {
   const configuredCodeRoot = path.resolve(root, result.workspace?.code_repository?.path || "code");
   const scan = sourceScan || scanProjectFiles(configuredCodeRoot);
@@ -840,16 +889,6 @@ function writeBootstrapArtifacts(root, initialState, result, sourceScan = null)
     recommended_task_id: result.runtime.recommended_task_id,
     updated_at: result.detected_at,
   }, { lineWidth: 0 }));
-  registerBootstrapReport(root, {
-    artifact_id: report.artifact_id,
-    artifact_type: report.artifact_type,
-    version: 1,
-    status: "draft",
-    producer_skill: "ai-delivery-bootstrap",
-    path: reportRef,
-    checksum_algorithm: "sha256",
-    checksum: reportChecksum,
-  });
   return {
     run_id: runId,
     report_ref: reportRef,
@@ -921,7 +960,9 @@ export function bootstrapProject(packageRoot, target, options = {}) {
       : shouldDeferToExternal
         ? `Wait for external input: ${result.runtime.next_action}`
         : shouldDeferToRecovery
-          ? `Resume task ${result.runtime.recommended_task_id} before any bootstrap mutation.`
+          ? result.runtime.recommended_status === "failed"
+            ? `Retry task ${result.runtime.recommended_task_id} with task-state.mjs activate --task-id ${result.runtime.recommended_task_id} --new-attempt --phase repair before any bootstrap mutation.`
+            : `Resume task ${result.runtime.recommended_task_id} before any bootstrap mutation.`
           : "Project bootstrap completed.",
   };
 }