@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/workflow-contract.js

@@ -0,0 +1,107 @@
+const STATUS = Object.freeze({
+  PASS: "PASS",
+  WARN: "WARN",
+  BLOCK: "BLOCK"
+});
+
+const STATUS_PRIORITY = Object.freeze({
+  PASS: 0,
+  WARN: 1,
+  BLOCK: 2
+});
+
+const STAGES = Object.freeze([
+  Object.freeze({
+    id: "bootstrap",
+    label: "Bootstrap",
+    defaultRoute: "da-vinci bootstrap-project --project <project-path> --change <change-id>"
+  }),
+  Object.freeze({
+    id: "breakdown",
+    label: "Breakdown",
+    defaultRoute: "/dv:breakdown"
+  }),
+  Object.freeze({
+    id: "design",
+    label: "Design",
+    defaultRoute: "/dv:design"
+  }),
+  Object.freeze({
+    id: "tasks",
+    label: "Tasks",
+    defaultRoute: "/dv:tasks"
+  }),
+  Object.freeze({
+    id: "build",
+    label: "Build",
+    defaultRoute: "/dv:build"
+  }),
+  Object.freeze({
+    id: "verify",
+    label: "Verify",
+    defaultRoute: "/dv:verify"
+  }),
+  Object.freeze({
+    id: "complete",
+    label: "Complete",
+    defaultRoute: null
+  })
+]);
+
+const STAGE_INDEX = Object.freeze(
+  STAGES.reduce((acc, stage, index) => {
+    acc[stage.id] = {
+      ...stage,
+      order: index + 1
+    };
+    return acc;
+  }, {})
+);
+
+const CHECKPOINT_LABELS = Object.freeze({
+  DESIGN: "design checkpoint",
+  MAPPING: "mapping checkpoint",
+  TASK: "task checkpoint",
+  DESIGN_SOURCE: "design source checkpoint",
+  RUNTIME_GATE: "mcp runtime gate"
+});
+
+const HANDOFF_GATES = Object.freeze({
+  BREAKDOWN_TO_DESIGN: "breakdown_to_design",
+  DESIGN_TO_TASKS: "design_to_tasks",
+  TASKS_TO_BUILD: "tasks_to_build",
+  BUILD_TO_VERIFY: "build_to_verify",
+  VERIFY_TO_COMPLETE: "verify_to_complete"
+});
+
+function getStageById(stageId) {
+  return STAGE_INDEX[stageId] || null;
+}
+
+function mergeStatuses(statuses) {
+  const normalized = (statuses || [])
+    .map((value) => String(value || "").toUpperCase())
+    .filter((value) => STATUS_PRIORITY[value] !== undefined);
+  if (normalized.length === 0) {
+    return STATUS.PASS;
+  }
+
+  let selected = STATUS.PASS;
+  for (const status of normalized) {
+    if (STATUS_PRIORITY[status] > STATUS_PRIORITY[selected]) {
+      selected = status;
+    }
+  }
+  return selected;
+}
+
+module.exports = {
+  STATUS,
+  STATUS_PRIORITY,
+  STAGES,
+  STAGE_INDEX,
+  CHECKPOINT_LABELS,
+  HANDOFF_GATES,
+  getStageById,
+  mergeStatuses
+};

package/lib/workflow-persisted-state.js

@@ -0,0 +1,297 @@
+const fs = require("fs");
+const path = require("path");
+const { writeFileAtomic, pathExists, readTextIfExists } = require("./utils");
+
+const WORKFLOW_STATE_VERSION = 1;
+const DEFAULT_STALE_WINDOW_MS = 24 * 60 * 60 * 1000;
+const PERSISTED_NOTE_EXCLUDE_PATTERNS = [
+  /^No persisted workflow state found for this change; deriving from artifacts\.$/i,
+  /^Persisted workflow state .* deriving from artifacts\.$/i,
+  /^workflow-status persisted a fresh derived workflow snapshot\.$/i,
+  /^Task-group metadata refreshed:/i
+];
+
+function resolveWorkflowStatePath(projectRoot) {
+  return path.join(projectRoot, ".da-vinci", "state", "workflow.json");
+}
+
+function resolveTaskGroupMetadataPath(projectRoot, changeId) {
+  return path.join(projectRoot, ".da-vinci", "state", "task-groups", `${changeId}.json`);
+}
+
+function fingerprintForPath(targetPath) {
+  if (!pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    const stat = fs.statSync(targetPath);
+    return {
+      path: targetPath,
+      mtimeMs: stat.mtimeMs,
+      size: stat.size
+    };
+  } catch (_error) {
+    return null;
+  }
+}
+
+function buildWorkflowFingerprint(projectRoot, changeId) {
+  const changeRoot = changeId ? path.join(projectRoot, ".da-vinci", "changes", changeId) : "";
+  const candidates = [
+    path.join(projectRoot, ".da-vinci", "page-map.md"),
+    path.join(changeRoot, "proposal.md"),
+    path.join(changeRoot, "design.md"),
+    path.join(changeRoot, "pencil-design.md"),
+    path.join(changeRoot, "pencil-bindings.md"),
+    path.join(changeRoot, "tasks.md"),
+    path.join(changeRoot, "verification.md"),
+    path.join(changeRoot, "workflow.json")
+  ];
+
+  const specRoot = path.join(changeRoot, "specs");
+  if (pathExists(specRoot)) {
+    const stack = [specRoot];
+    const visited = new Set();
+    while (stack.length > 0) {
+      const current = stack.pop();
+      let resolvedCurrent;
+      try {
+        resolvedCurrent = fs.realpathSync(current);
+      } catch (_error) {
+        continue;
+      }
+      if (visited.has(resolvedCurrent)) {
+        continue;
+      }
+      visited.add(resolvedCurrent);
+
+      let entries = [];
+      try {
+        entries = fs.readdirSync(current, { withFileTypes: true });
+      } catch (_error) {
+        continue;
+      }
+      for (const entry of entries) {
+        const absolutePath = path.join(current, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink()) {
+          stack.push(absolutePath);
+          continue;
+        }
+        if (entry.isFile() && entry.name === "spec.md") {
+          candidates.push(absolutePath);
+        }
+      }
+    }
+  }
+
+  return candidates
+    .map((candidate) => fingerprintForPath(candidate))
+    .filter(Boolean)
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function stableFingerprintHash(fingerprint) {
+  return JSON.stringify(
+    (fingerprint || []).map((entry) => ({
+      path: entry.path,
+      mtimeMs: entry.mtimeMs,
+      size: entry.size
+    }))
+  );
+}
+
+function sanitizePersistedNotes(notes) {
+  const filtered = [];
+  for (const note of Array.isArray(notes) ? notes : []) {
+    const text = String(note || "").trim();
+    if (!text) {
+      continue;
+    }
+    if (PERSISTED_NOTE_EXCLUDE_PATTERNS.some((pattern) => pattern.test(text))) {
+      continue;
+    }
+    filtered.push(text);
+  }
+  return Array.from(new Set(filtered));
+}
+
+function readPersistedWorkflowState(projectRoot) {
+  const statePath = resolveWorkflowStatePath(projectRoot);
+  if (!pathExists(statePath)) {
+    return {
+      statePath,
+      state: null
+    };
+  }
+
+  try {
+    const payload = JSON.parse(readTextIfExists(statePath));
+    return {
+      statePath,
+      state: payload
+    };
+  } catch (_error) {
+    return {
+      statePath,
+      state: null,
+      parseError: true
+    };
+  }
+}
+
+function writePersistedWorkflowState(projectRoot, payload) {
+  const statePath = resolveWorkflowStatePath(projectRoot);
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  writeFileAtomic(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+  return statePath;
+}
+
+function selectPersistedStateForChange(projectRoot, changeId, options = {}) {
+  const staleWindowMs = Number.isFinite(Number(options.staleWindowMs))
+    ? Number(options.staleWindowMs)
+    : DEFAULT_STALE_WINDOW_MS;
+
+  const loaded = readPersistedWorkflowState(projectRoot);
+  if (!loaded.state) {
+    return {
+      usable: false,
+      reason: loaded.parseError ? "parse-error" : "missing",
+      statePath: loaded.statePath,
+      persisted: null
+    };
+  }
+
+  if (loaded.state.version !== WORKFLOW_STATE_VERSION) {
+    return {
+      usable: false,
+      reason: "version-mismatch",
+      statePath: loaded.statePath,
+      persisted: loaded.state
+    };
+  }
+
+  const byChange = loaded.state.changes || {};
+  const changeRecord = changeId ? byChange[changeId] : null;
+  if (!changeRecord) {
+    return {
+      usable: false,
+      reason: "change-missing",
+      statePath: loaded.statePath,
+      persisted: loaded.state
+    };
+  }
+
+  const persistedAt = Date.parse(String(changeRecord.persistedAt || ""));
+  if (!Number.isFinite(persistedAt)) {
+    return {
+      usable: false,
+      reason: "invalid-timestamp",
+      statePath: loaded.statePath,
+      persisted: loaded.state
+    };
+  }
+
+  if (Date.now() - persistedAt > staleWindowMs) {
+    return {
+      usable: false,
+      reason: "time-stale",
+      statePath: loaded.statePath,
+      persisted: loaded.state
+    };
+  }
+
+  const currentFingerprint = buildWorkflowFingerprint(projectRoot, changeId);
+  const currentHash = stableFingerprintHash(currentFingerprint);
+  const persistedHash = String(changeRecord.fingerprintHash || "");
+  if (!persistedHash || persistedHash !== currentHash) {
+    return {
+      usable: false,
+      reason: "fingerprint-mismatch",
+      statePath: loaded.statePath,
+      persisted: loaded.state
+    };
+  }
+
+  return {
+    usable: true,
+    reason: null,
+    statePath: loaded.statePath,
+    persisted: loaded.state,
+    changeRecord
+  };
+}
+
+function persistDerivedWorkflowResult(projectRoot, changeId, workflowResult, options = {}) {
+  const loaded = readPersistedWorkflowState(projectRoot);
+  const current = loaded.state && typeof loaded.state === "object" ? loaded.state : {};
+  const changes = current.changes && typeof current.changes === "object" ? current.changes : {};
+  const metadataRefs = options.metadataRefs || {};
+
+  if (!changeId) {
+    return resolveWorkflowStatePath(projectRoot);
+  }
+
+  const fingerprint = buildWorkflowFingerprint(projectRoot, changeId);
+  changes[changeId] = {
+    stage: workflowResult.stage,
+    checkpointState: workflowResult.checkpointState,
+    gates: workflowResult.gates,
+    nextStep: workflowResult.nextStep,
+    status: workflowResult.status,
+    failures: workflowResult.failures,
+    warnings: workflowResult.warnings,
+    notes: sanitizePersistedNotes(workflowResult.notes),
+    taskGroups: workflowResult.taskGroups || null,
+    metadataRefs,
+    fingerprintHash: stableFingerprintHash(fingerprint),
+    persistedAt: new Date().toISOString()
+  };
+
+  const payload = {
+    version: WORKFLOW_STATE_VERSION,
+    updatedAt: new Date().toISOString(),
+    changes
+  };
+  return writePersistedWorkflowState(projectRoot, payload);
+}
+
+function writeTaskGroupMetadata(projectRoot, changeId, metadataPayload) {
+  if (!changeId) {
+    return null;
+  }
+  const targetPath = resolveTaskGroupMetadataPath(projectRoot, changeId);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  writeFileAtomic(targetPath, `${JSON.stringify(metadataPayload, null, 2)}\n`);
+  return targetPath;
+}
+
+function readTaskGroupMetadata(projectRoot, changeId) {
+  if (!changeId) {
+    return null;
+  }
+  const targetPath = resolveTaskGroupMetadataPath(projectRoot, changeId);
+  if (!pathExists(targetPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readTextIfExists(targetPath));
+  } catch (_error) {
+    return null;
+  }
+}
+
+module.exports = {
+  WORKFLOW_STATE_VERSION,
+  DEFAULT_STALE_WINDOW_MS,
+  resolveWorkflowStatePath,
+  resolveTaskGroupMetadataPath,
+  buildWorkflowFingerprint,
+  stableFingerprintHash,
+  sanitizePersistedNotes,
+  readPersistedWorkflowState,
+  writePersistedWorkflowState,
+  selectPersistedStateForChange,
+  persistDerivedWorkflowResult,
+  writeTaskGroupMetadata,
+  readTaskGroupMetadata
+};