@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/sidecars.js

@@ -0,0 +1,369 @@
+const fs = require("fs");
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const { pathExists, writeFileAtomic } = require("./utils");
+const {
+  unique,
+  resolveChangeDir,
+  parseTasksArtifact,
+  parseBindingsArtifact,
+  parsePageMapArtifact,
+  parseRuntimeSpecs,
+  digestFile,
+  digestObject,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+
+const SCHEMA_VERSION = "1.0.0";
+
+function buildEnvelope(projectRoot) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    sidecarsDir: null,
+    sidecars: {},
+    freshness: {}
+  };
+}
+
+function normalizeCollectionItems(values) {
+  return unique((values || []).map((value) => String(value || "").trim()).filter(Boolean)).sort((a, b) =>
+    a.localeCompare(b)
+  );
+}
+
+function buildSpecIndex(projectRoot, changeId, specRecords) {
+  const behaviors = [];
+  const states = [];
+  const inputs = [];
+  const outputs = [];
+  const acceptance = [];
+  const sourceRefs = [];
+
+  for (const record of specRecords) {
+    const sourcePath = record.path;
+    sourceRefs.push({
+      path: sourcePath,
+      digest: digestFile(path.join(projectRoot, sourcePath))
+    });
+
+    const parsed = record.parsed;
+    for (const item of parsed.sections.behavior.items || []) {
+      behaviors.push({ specPath: sourcePath, text: item });
+    }
+    for (const item of parsed.sections.states.items || []) {
+      states.push({ specPath: sourcePath, text: item });
+    }
+    for (const item of parsed.sections.inputs.items || []) {
+      inputs.push({ specPath: sourcePath, text: item });
+    }
+    for (const item of parsed.sections.outputs.items || []) {
+      outputs.push({ specPath: sourcePath, text: item });
+    }
+    for (const item of parsed.sections.acceptance.items || []) {
+      acceptance.push({ specPath: sourcePath, text: item });
+    }
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sidecar: "spec.index.json",
+    changeId,
+    sourceRefs: sourceRefs.sort((a, b) => a.path.localeCompare(b.path)),
+    collections: {
+      behavior: behaviors
+        .map((item, index) => ({
+          id: `behavior-${String(index + 1).padStart(3, "0")}`,
+          specPath: item.specPath,
+          text: item.text
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+      states: states
+        .map((item, index) => ({
+          id: `state-${String(index + 1).padStart(3, "0")}`,
+          specPath: item.specPath,
+          text: item.text
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+      inputs: inputs
+        .map((item, index) => ({
+          id: `input-${String(index + 1).padStart(3, "0")}`,
+          specPath: item.specPath,
+          text: item.text
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+      outputs: outputs
+        .map((item, index) => ({
+          id: `output-${String(index + 1).padStart(3, "0")}`,
+          specPath: item.specPath,
+          text: item.text
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+      acceptance: acceptance
+        .map((item, index) => ({
+          id: `acceptance-${String(index + 1).padStart(3, "0")}`,
+          specPath: item.specPath,
+          text: item.text
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id))
+    }
+  };
+}
+
+function buildTasksIndex(changeId, tasksArtifact, bindingsArtifact, specIndex) {
+  const taskSections = Array.isArray(tasksArtifact.sections) ? tasksArtifact.sections : [];
+  const groupRecords = tasksArtifact.taskGroups.map((group) => {
+    const section =
+      taskSections.find((item) => String(item.id || "") === String(group.id || "")) || null;
+    const checklistItems = Array.isArray(section && section.checklistItems)
+      ? section.checklistItems
+      : [];
+    return {
+      id: String(group.id || ""),
+      title: group.title,
+      checklistItems: checklistItems.map((item) => ({
+        checked: item.checked,
+        text: item.text
+      }))
+    };
+  });
+
+  const specTexts = [
+    ...specIndex.collections.behavior.map((item) => item.text),
+    ...specIndex.collections.states.map((item) => item.text),
+    ...specIndex.collections.acceptance.map((item) => item.text)
+  ]
+    .join(" ")
+    .toLowerCase();
+
+  const specLinks = groupRecords.map((group) => {
+    const tokens = String(group.title || "")
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((token) => token.length >= 4);
+    const matchedTokenCount = tokens.filter((token) => specTexts.includes(token)).length;
+    return {
+      taskGroupId: group.id,
+      matchedTokenCount
+    };
+  });
+
+  const bindingLinks = bindingsArtifact.mappings.map((mapping, index) => ({
+    id: `binding-link-${String(index + 1).padStart(3, "0")}`,
+    implementation: mapping.implementation,
+    designPage: mapping.designPage,
+    designSource: mapping.designSource || ""
+  }));
+
+  const codeAreas = normalizeCollectionItems(
+    tasksArtifact.checklistItems
+      .map((item) => item.text)
+      .filter((text) => /src\/|pages\/|component|module|route|screen/i.test(text))
+  );
+  const verificationActions = normalizeCollectionItems(
+    tasksArtifact.checklistItems
+      .map((item) => item.text)
+      .filter((text) => /verify|verification|coverage|test/i.test(text))
+  );
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sidecar: "tasks.index.json",
+    changeId,
+    sourceRefs: [],
+    taskGroups: groupRecords,
+    specLinks,
+    bindingLinks,
+    codeAreas,
+    verificationActions
+  };
+}
+
+function buildPageMapIndex(changeId, pageMapArtifact, pageMapPath, projectRoot) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sidecar: "page-map.index.json",
+    changeId,
+    sourceRefs: [
+      {
+        path: path.relative(projectRoot, pageMapPath) || pageMapPath,
+        digest: digestFile(pageMapPath)
+      }
+    ],
+    pages: pageMapArtifact.pages,
+    statesPerPageItems: pageMapArtifact.statesPerPageItems
+  };
+}
+
+function buildBindingsIndex(changeId, bindingsArtifact, bindingsPath, projectRoot) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sidecar: "bindings.index.json",
+    changeId,
+    sourceRefs: [
+      {
+        path: path.relative(projectRoot, bindingsPath) || bindingsPath,
+        digest: digestFile(bindingsPath)
+      }
+    ],
+    mappings: bindingsArtifact.mappings
+      .map((mapping, index) => ({
+        id: `mapping-${String(index + 1).padStart(3, "0")}`,
+        implementation: mapping.implementation,
+        designPage: mapping.designPage,
+        designSource: mapping.designSource || "",
+        screenId: mapping.screenId || ""
+      }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+    malformed: bindingsArtifact.malformed.sort((a, b) => a.localeCompare(b))
+  };
+}
+
+function attachTaskSources(tasksIndex, artifactPaths, projectRoot) {
+  tasksIndex.sourceRefs = [
+    { path: path.relative(projectRoot, artifactPaths.tasksPath), digest: digestFile(artifactPaths.tasksPath) },
+    {
+      path: path.relative(projectRoot, artifactPaths.bindingsPath),
+      digest: digestFile(artifactPaths.bindingsPath)
+    }
+  ];
+  return tasksIndex;
+}
+
+function writeSidecarFile(sidecarsDir, fileName, payload) {
+  const absolutePath = path.join(sidecarsDir, fileName);
+  writeFileAtomic(absolutePath, `${JSON.stringify(payload, null, 2)}\n`);
+  return absolutePath;
+}
+
+function generatePlanningSidecars(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const write = options.write !== false;
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const result = buildEnvelope(projectRoot);
+
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  result.failures.push(...resolved.failures);
+  result.notes.push(...resolved.notes);
+  if (!resolved.changeDir) {
+    result.status = STATUS.BLOCK;
+    return result;
+  }
+  result.changeId = resolved.changeId;
+
+  const artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+  const artifacts = readArtifactTexts(artifactPaths);
+  const specRecords = parseRuntimeSpecs(resolved.changeDir, projectRoot);
+  if (!artifacts.tasks || !artifacts.bindings || !artifacts.pageMap || specRecords.length === 0) {
+    if (!artifacts.tasks) {
+      result.failures.push("Missing `tasks.md` for sidecar generation.");
+    }
+    if (!artifacts.bindings) {
+      result.failures.push("Missing `pencil-bindings.md` for sidecar generation.");
+    }
+    if (!artifacts.pageMap) {
+      result.failures.push("Missing `page-map.md` for sidecar generation.");
+    }
+    if (specRecords.length === 0) {
+      result.failures.push("Missing runtime spec files for sidecar generation.");
+    }
+    result.status = STATUS.BLOCK;
+    return result;
+  }
+
+  const tasksArtifact = parseTasksArtifact(artifacts.tasks);
+  const bindingsArtifact = parseBindingsArtifact(artifacts.bindings);
+  const pageMapArtifact = parsePageMapArtifact(artifacts.pageMap);
+
+  const specIndex = buildSpecIndex(projectRoot, resolved.changeId, specRecords);
+  const tasksIndex = attachTaskSources(
+    buildTasksIndex(resolved.changeId, tasksArtifact, bindingsArtifact, specIndex),
+    artifactPaths,
+    projectRoot
+  );
+  const pageMapIndex = buildPageMapIndex(resolved.changeId, pageMapArtifact, artifactPaths.pageMapPath, projectRoot);
+  const bindingsIndex = buildBindingsIndex(
+    resolved.changeId,
+    bindingsArtifact,
+    artifactPaths.bindingsPath,
+    projectRoot
+  );
+
+  const sidecars = {
+    "spec.index.json": specIndex,
+    "tasks.index.json": tasksIndex,
+    "page-map.index.json": pageMapIndex,
+    "bindings.index.json": bindingsIndex
+  };
+
+  result.sidecars = sidecars;
+  result.freshness = Object.fromEntries(
+    Object.entries(sidecars).map(([name, payload]) => [name, digestObject(payload)])
+  );
+
+  const sidecarsDir = path.join(resolved.changeDir, "sidecars");
+  result.sidecarsDir = sidecarsDir;
+
+  if (write) {
+    fs.mkdirSync(sidecarsDir, { recursive: true });
+    const written = {};
+    for (const [name, payload] of Object.entries(sidecars)) {
+      written[name] = writeSidecarFile(sidecarsDir, name, payload);
+    }
+    result.written = written;
+    result.notes.push("Sidecars are generated only through `generate-sidecars`; lint/status/verify do not auto-rewrite them.");
+  } else {
+    result.notes.push("Dry-run mode: sidecars computed in-memory only.");
+  }
+
+  return result;
+}
+
+function formatGenerateSidecarsReport(result) {
+  const lines = [
+    "Da Vinci generate-sidecars",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Status: ${result.status}`
+  ];
+
+  if (result.sidecarsDir) {
+    lines.push(`Sidecars dir: ${result.sidecarsDir}`);
+  }
+  if (result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  if (Object.keys(result.freshness || {}).length > 0) {
+    lines.push("", "Sidecar digests:");
+    for (const [name, digest] of Object.entries(result.freshness)) {
+      lines.push(`- ${name}: ${digest}`);
+    }
+  }
+  if (result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  generatePlanningSidecars,
+  formatGenerateSidecarsReport
+};

package/lib/supervisor-review.js

@@ -111,13 +111,25 @@ function buildReviewerPrompt({ reviewer, projectRoot, changeId, pencilDesignPath
   ].join("\n");
 }
 
+function truncateForError(value, maxLength = 240) {
+  const text = String(value || "").replace(/\s+/g, " ").trim();
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}...`;
+}
+
 function parseReviewerPayload(rawText) {
   const payload = parseJsonText(String(rawText || "").trim(), "reviewer JSON payload");
   if (!isPlainObject(payload)) {
-    throw new Error("Invalid reviewer JSON payload: expected a JSON object.");
+    throw new Error(
+      `Invalid reviewer JSON payload: expected a JSON object. Received: ${truncateForError(rawText)}`
+    );
   }
   if (!payload.status) {
-    throw new Error("Invalid reviewer JSON payload: missing required `status`.");
+    throw new Error(
+      `Invalid reviewer JSON payload: missing required \`status\`. Received: ${truncateForError(rawText)}`
+    );
   }
   const status = normalizeStatus(payload.status);
   const issues = Array.isArray(payload.issues)
@@ -241,7 +253,20 @@ async function runReviewerWithCodexOnce(options = {}) {
       const stdout = String(error.stdout || "").trim();
       const stderr = String(error.stderr || "").trim();
       const timeoutHint = error.killed ? " (timed out)" : "";
-      const message = stderr || stdout || error.message || "unknown error";
+      const diagnostics = [];
+      if (stderr) {
+        diagnostics.push(stderr);
+      }
+      if (stdout) {
+        diagnostics.push(`stdout: ${stdout}`);
+      }
+      if (error && error.code !== undefined && error.code !== null && !stderr && !stdout) {
+        diagnostics.push(`process code: ${String(error.code)}`);
+      }
+      if (error && error.signal && !stderr && !stdout) {
+        diagnostics.push(`signal: ${String(error.signal)}`);
+      }
+      const message = diagnostics[0] || error.message || "unclassified execution failure";
       throw new Error(`Reviewer \`${reviewer}\` failed${timeoutHint}: ${message}`);
     }
 

package/lib/utils.js

@@ -90,8 +90,16 @@ function writeFileAtomic(targetPath, content, options = {}) {
   const encoding = options.encoding || "utf8";
   const tempPath = buildAtomicTempPath(resolvedTargetPath);
   fs.mkdirSync(path.dirname(resolvedTargetPath), { recursive: true });
-  fs.writeFileSync(tempPath, content, encoding);
-  fs.renameSync(tempPath, resolvedTargetPath);
+  let shouldCleanupTemp = true;
+  try {
+    fs.writeFileSync(tempPath, content, encoding);
+    fs.renameSync(tempPath, resolvedTargetPath);
+    shouldCleanupTemp = false;
+  } finally {
+    if (shouldCleanupTemp) {
+      fs.rmSync(tempPath, { force: true });
+    }
+  }
 }
 
 function writeFileExclusiveAtomic(targetPath, content, options = {}) {