@xenonbyte/da-vinci-workflow 0.1.14 → 0.1.16

package/lib/cli.js

@@ -1,3 +1,4 @@
+const fs = require("fs");
 const {
   VERSION,
   installPlatforms,
@@ -5,6 +6,16 @@ const {
   getStatus,
   validateAssets
 } = require("./install");
+const { auditProject, formatAuditReport } = require("./audit");
+const {
+  preflightPencilBatch,
+  formatPencilPreflightReport,
+  readOperations
+} = require("./pencil-preflight");
+const {
+  writePenFromPayloadFiles,
+  snapshotPenFile
+} = require("./pen-persistence");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -20,6 +31,31 @@ function getOption(args, name) {
   return undefined;
 }
 
+function getPositionalArgs(args, optionsWithValues = []) {
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (optionsWithValues.includes(arg)) {
+      index += 1;
+      continue;
+    }
+
+    if (optionsWithValues.some((name) => arg.startsWith(`${name}=`))) {
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  return positional;
+}
+
 function formatStatus(status) {
   return [
     `Da Vinci v${status.version}`,
@@ -40,11 +76,25 @@ function printHelp() {
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
       "  da-vinci validate-assets",
+      "  da-vinci audit [project-path]",
+      "  da-vinci preflight-pencil --ops-file <path>",
+      "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci snapshot-pen --input <path> --output <path>",
       "  da-vinci --version",
       "",
       "Options:",
       "  --platform <value>   codex, claude, gemini, or all",
-      "  --home <path>        override HOME for installation targets"
+      "  --home <path>        override HOME for installation targets",
+      "  --project <path>     override project path for audit",
+      "  --ops-file <path>    Pencil batch operations file for preflight",
+      "  --input <path>       input .pen file for snapshot-pen",
+      "  --output <path>      output .pen file for write-pen or snapshot-pen",
+      "  --nodes-file <path>  JSON payload from batch_get for write-pen",
+      "  --variables-file <path> JSON payload from get_variables for write-pen",
+      "  --verify-open        reopen the written .pen with Pencil after writing",
+      "  --version <value>    explicit .pen version when writing from MCP payloads",
+      "  --mode <value>       integrity or completion",
+      "  --change <id>        scope completion audit to one change id"
     ].join("\n")
   );
 }
@@ -52,6 +102,7 @@ function printHelp() {
 async function runCli(argv) {
   const [command] = argv;
   const homeDir = getOption(argv, "--home");
+  const positionalArgs = getPositionalArgs(argv.slice(1), ["--home", "--platform", "--project", "--mode", "--change"]);
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -92,6 +143,96 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "audit") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const mode = getOption(argv, "--mode");
+    const changeId = getOption(argv, "--change");
+    const result = auditProject(projectPath, { mode, changeId });
+    const report = formatAuditReport(result);
+
+    if (result.status === "FAIL") {
+      throw new Error(report);
+    }
+
+    console.log(report);
+    return;
+  }
+
+  if (command === "preflight-pencil") {
+    const opsFile = getOption(argv, "--ops-file");
+    let operations = "";
+
+    if (opsFile) {
+      operations = readOperations(opsFile);
+    } else if (!process.stdin.isTTY) {
+      operations = fs.readFileSync(0, "utf8");
+    } else {
+      throw new Error("`preflight-pencil` requires `--ops-file <path>` or piped stdin input.");
+    }
+
+    const result = preflightPencilBatch(operations);
+    const report = formatPencilPreflightReport(result);
+
+    if (result.status === "FAIL") {
+      throw new Error(report);
+    }
+
+    console.log(report);
+    return;
+  }
+
+  if (command === "write-pen") {
+    const outputPath = getOption(argv, "--output");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!outputPath || !nodesFile) {
+      throw new Error("`write-pen` requires `--output <path>` and `--nodes-file <path>`.");
+    }
+
+    const result = writePenFromPayloadFiles({
+      outputPath,
+      nodesFile,
+      variablesFile,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`Wrote .pen file to ${result.outputPath}`);
+    console.log(`Top-level nodes: ${result.document.children.length}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    return;
+  }
+
+  if (command === "snapshot-pen") {
+    const inputPath = getOption(argv, "--input");
+    const outputPath = getOption(argv, "--output");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!inputPath || !outputPath) {
+      throw new Error("`snapshot-pen` requires `--input <path>` and `--output <path>`.");
+    }
+
+    const result = snapshotPenFile({
+      inputPath,
+      outputPath,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`Snapshotted ${result.inputPath} to ${result.outputPath}`);
+    console.log(`Top-level nodes: ${result.document.children.length}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 

package/lib/mcp-runtime-gate.js

@@ -0,0 +1,342 @@
+const path = require("path");
+
+const PASS = "PASS";
+const WARN = "WARN";
+const BLOCK = "BLOCK";
+const SKIP = "SKIP";
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value.filter(Boolean) : [];
+}
+
+function normalizeLiveScreens(liveScreens) {
+  return normalizeArray(liveScreens).map((screen) => ({
+    id: screen && screen.id ? String(screen.id) : "",
+    name: screen && screen.name ? String(screen.name) : ""
+  }));
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function getScreenIds(liveScreens) {
+  return unique(normalizeLiveScreens(liveScreens).map((screen) => screen.id).filter(Boolean));
+}
+
+function getScreenNames(liveScreens) {
+  return unique(normalizeLiveScreens(liveScreens).map((screen) => screen.name).filter(Boolean));
+}
+
+function normalizeEditorName(activeEditor) {
+  return typeof activeEditor === "string" ? activeEditor.trim() : "";
+}
+
+function normalizeRegisteredPath(registeredPenPath) {
+  return typeof registeredPenPath === "string" ? registeredPenPath.trim() : "";
+}
+
+function resolveProjectPath(projectRoot, targetPath) {
+  if (!targetPath) {
+    return "";
+  }
+
+  if (path.isAbsolute(targetPath)) {
+    return path.normalize(targetPath);
+  }
+
+  if (!projectRoot) {
+    return "";
+  }
+
+  return path.normalize(path.resolve(projectRoot, targetPath));
+}
+
+function isUnnamedEditor(activeEditor) {
+  const normalized = normalizeEditorName(activeEditor).toLowerCase();
+  return normalized === "" || normalized === "new";
+}
+
+function matchesRegisteredPath(activeEditor, registeredPenPath, projectRoot) {
+  const editor = normalizeEditorName(activeEditor);
+  const registered = normalizeRegisteredPath(registeredPenPath);
+
+  if (!editor || !registered) {
+    return false;
+  }
+
+  const resolvedEditor = resolveProjectPath(projectRoot, editor);
+  const resolvedRegistered = resolveProjectPath(projectRoot, registered);
+
+  if (resolvedEditor && resolvedRegistered) {
+    return resolvedEditor === resolvedRegistered;
+  }
+
+  const editorHasPathSeparators = editor.includes("/") || editor.includes("\\");
+  if (editorHasPathSeparators) {
+    return false;
+  }
+
+  return path.basename(editor) === path.basename(registered);
+}
+
+function missingIds(expectedIds, actualIds) {
+  const actualSet = new Set(actualIds);
+  return unique(expectedIds).filter((id) => !actualSet.has(id));
+}
+
+function derivePhase(snapshot) {
+  return snapshot.phase || "completion";
+}
+
+function evaluateSourceConvergence(snapshot) {
+  const notes = [];
+  const activeEditor = normalizeEditorName(snapshot.activeEditor);
+  const registeredPenPath = normalizeRegisteredPath(snapshot.registeredPenPath);
+  const projectRoot = typeof snapshot.projectRoot === "string" ? snapshot.projectRoot.trim() : "";
+  const shellVisiblePenExists = Boolean(snapshot.shellVisiblePenExists);
+  const documentedReconciliation = Boolean(snapshot.documentedReconciliation);
+  const noNewPencilEditsYet = Boolean(snapshot.noNewPencilEditsYet);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so runtime source convergence could not be fully checked."]
+    };
+  }
+
+  if (isUnnamedEditor(activeEditor)) {
+    return {
+      status: BLOCK,
+      notes: ["Active Pencil editor is still an unnamed live document such as `new`."]
+    };
+  }
+
+  if (!registeredPenPath) {
+    return {
+      status: BLOCK,
+      notes: ["No registered project-local `.pen` path was provided for runtime comparison."]
+    };
+  }
+
+  if (!shellVisiblePenExists) {
+    return {
+      status: BLOCK,
+      notes: ["The registered project-local `.pen` file is not shell-visible on disk."]
+    };
+  }
+
+  if (!matchesRegisteredPath(activeEditor, registeredPenPath, projectRoot)) {
+    if (documentedReconciliation) {
+      return {
+        status: WARN,
+        notes: [
+          "Active Pencil editor does not match the registered project-local `.pen` path, but a documented reconciliation was provided."
+        ]
+      };
+    }
+
+    return {
+      status: BLOCK,
+      notes: ["Active Pencil editor does not match the registered project-local `.pen` path."]
+    };
+  }
+
+  if (noNewPencilEditsYet) {
+    notes.push("No new Pencil edits were recorded yet; source convergence is only provisionally confirmed.");
+    return {
+      status: WARN,
+      notes
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk."]
+  };
+}
+
+function evaluateScreenPresence(snapshot) {
+  const phase = derivePhase(snapshot);
+  const claimedAnchorIds = normalizeArray(snapshot.claimedAnchorIds);
+  const claimedReviewedScreenIds = normalizeArray(snapshot.claimedReviewedScreenIds);
+  const reviewTargets = normalizeArray(snapshot.reviewTargets);
+  const liveIds = getScreenIds(snapshot.liveScreens);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so live screen presence could not be fully checked."]
+    };
+  }
+
+  if (phase === "first_write" && claimedAnchorIds.length === 0 && claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    return {
+      status: SKIP,
+      notes: ["No anchor or review ids were declared yet, so screen-presence checks were skipped at first-write stage."]
+    };
+  }
+
+  const missingAnchorIds = missingIds(claimedAnchorIds, liveIds);
+  const missingReviewedIds = missingIds(claimedReviewedScreenIds, liveIds);
+  const missingReviewTargets = missingIds(reviewTargets, liveIds);
+
+  const notes = [];
+  if (missingAnchorIds.length > 0) {
+    notes.push(`Missing claimed anchor ids in the active editor: ${missingAnchorIds.join(", ")}`);
+  }
+  if (missingReviewedIds.length > 0) {
+    notes.push(`Missing claimed reviewed screen ids in the active editor: ${missingReviewedIds.join(", ")}`);
+  }
+  if (missingReviewTargets.length > 0) {
+    notes.push(`Missing screenshot target ids in the active editor: ${missingReviewTargets.join(", ")}`);
+  }
+
+  if (notes.length > 0) {
+    return {
+      status: BLOCK,
+      notes
+    };
+  }
+
+  if (claimedAnchorIds.length === 0 && claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    return {
+      status: WARN,
+      notes: ["No claimed anchor, reviewed, or screenshot target ids were provided for runtime verification."]
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Claimed anchor surfaces and review targets resolve in the active live editor."]
+  };
+}
+
+function evaluateReviewExecution(snapshot) {
+  const phase = derivePhase(snapshot);
+  const claimedReviewedScreenIds = normalizeArray(snapshot.claimedReviewedScreenIds);
+  const reviewTargets = normalizeArray(snapshot.reviewTargets);
+  const reviewBlockersIgnored = Boolean(snapshot.reviewBlockersIgnored);
+  const broadExpansionRequested = Boolean(snapshot.broadExpansionRequested);
+
+  if (Boolean(snapshot.mcpAvailable) === false) {
+    return {
+      status: WARN,
+      notes: ["Pencil MCP is unavailable, so runtime review execution could not be fully checked."]
+    };
+  }
+
+  if (phase === "first_write") {
+    return {
+      status: SKIP,
+      notes: ["Screenshot review is not required at first-write stage."]
+    };
+  }
+
+  if (claimedReviewedScreenIds.length === 0 && reviewTargets.length === 0) {
+    if (phase === "completion" || broadExpansionRequested) {
+      return {
+        status: BLOCK,
+        notes: ["No reviewed screen ids or screenshot targets were recorded for a stage that requires runtime review evidence."]
+      };
+    }
+
+    return {
+      status: WARN,
+      notes: ["No reviewed screen ids or screenshot targets were recorded yet."]
+    };
+  }
+
+  if (reviewBlockersIgnored) {
+    return {
+      status: BLOCK,
+      notes: ["Screenshot review recorded blocker-level issues that were ignored while the surface was still treated as approved."]
+    };
+  }
+
+  return {
+    status: PASS,
+    notes: ["Runtime review evidence exists for the approved surfaces."]
+  };
+}
+
+function combineStatuses(statuses) {
+  if (statuses.includes(BLOCK)) {
+    return BLOCK;
+  }
+  if (statuses.includes(WARN)) {
+    return WARN;
+  }
+  if (statuses.every((status) => status === SKIP)) {
+    return WARN;
+  }
+  return PASS;
+}
+
+function evaluateMcpRuntimeGate(snapshot = {}) {
+  const sourceConvergence = evaluateSourceConvergence(snapshot);
+  const screenPresence = evaluateScreenPresence(snapshot);
+  const reviewExecution = evaluateReviewExecution(snapshot);
+
+  const finalStatus = combineStatuses([
+    sourceConvergence.status,
+    screenPresence.status === SKIP ? PASS : screenPresence.status,
+    reviewExecution.status === SKIP ? PASS : reviewExecution.status
+  ]);
+
+  return {
+    phase: derivePhase(snapshot),
+    sourceConvergence,
+    screenPresence,
+    reviewExecution,
+    finalStatus,
+    activeEditor: normalizeEditorName(snapshot.activeEditor),
+    registeredPenPath:
+      typeof snapshot.registeredPenPath === "string" ? snapshot.registeredPenPath.trim() : "",
+    shellVisiblePenPath:
+      typeof snapshot.shellVisiblePenPath === "string" ? snapshot.shellVisiblePenPath.trim() : "",
+    shellVisiblePenExists: Boolean(snapshot.shellVisiblePenExists),
+    claimedAnchorIds: normalizeArray(snapshot.claimedAnchorIds),
+    claimedReviewedScreenIds: normalizeArray(snapshot.claimedReviewedScreenIds),
+    reviewTargets: normalizeArray(snapshot.reviewTargets),
+    liveScreenIds: getScreenIds(snapshot.liveScreens),
+    liveScreenNames: getScreenNames(snapshot.liveScreens)
+  };
+}
+
+function formatMcpRuntimeGateSection(snapshot, result, options = {}) {
+  const timestamp = options.timestamp || new Date().toISOString();
+  const notes = [
+    ...result.sourceConvergence.notes,
+    ...result.screenPresence.notes,
+    ...result.reviewExecution.notes
+  ];
+
+  return [
+    "## MCP Runtime Gate",
+    `- Time: ${timestamp}`,
+    `- Phase: ${result.phase}`,
+    `- Active editor: ${result.activeEditor || "(unavailable)"}`,
+    `- Registered \`.pen\` path: ${result.registeredPenPath || "(missing)"}`,
+    `- Shell-visible \`.pen\` path: ${result.shellVisiblePenPath || "(missing)"}`,
+    `- Shell-visible \`.pen\` exists: ${result.shellVisiblePenExists ? "yes" : "no"}`,
+    `- Claimed anchor ids: ${result.claimedAnchorIds.length > 0 ? result.claimedAnchorIds.join(", ") : "(none)"}`,
+    `- Reviewed screen ids: ${result.claimedReviewedScreenIds.length > 0 ? result.claimedReviewedScreenIds.join(", ") : "(none)"}`,
+    `- Screenshot target ids: ${result.reviewTargets.length > 0 ? result.reviewTargets.join(", ") : "(none)"}`,
+    `- Live screen ids: ${result.liveScreenIds.length > 0 ? result.liveScreenIds.join(", ") : "(none)"}`,
+    `- Source convergence: ${result.sourceConvergence.status}`,
+    `- Screen presence: ${result.screenPresence.status}`,
+    `- Review execution: ${result.reviewExecution.status}`,
+    `- Final runtime gate status: ${result.finalStatus}`,
+    `- Notes: ${notes.length > 0 ? notes.join(" | ") : "none"}`
+  ].join("\n");
+}
+
+module.exports = {
+  PASS,
+  WARN,
+  BLOCK,
+  SKIP,
+  evaluateMcpRuntimeGate,
+  formatMcpRuntimeGateSection
+};