@xenonbyte/da-vinci-workflow 0.1.15 → 0.1.17

package/lib/cli.js

@@ -1,3 +1,4 @@
+const fs = require("fs");
 const {
   VERSION,
   installPlatforms,
@@ -6,6 +7,28 @@ const {
   validateAssets
 } = require("./install");
 const { auditProject, formatAuditReport } = require("./audit");
+const {
+  preflightPencilBatch,
+  formatPencilPreflightReport,
+  readOperations
+} = require("./pencil-preflight");
+const {
+  writePenFromPayloadFiles,
+  snapshotPenFile,
+  ensurePenFile,
+  comparePenSync
+} = require("./pen-persistence");
+const {
+  acquirePencilLock,
+  releasePencilLock,
+  getPencilLockStatus
+} = require("./pencil-lock");
+const {
+  beginPencilSession,
+  persistPencilSession,
+  endPencilSession,
+  getPencilSessionStatus
+} = require("./pencil-session");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -67,14 +90,37 @@ function printHelp() {
       "  da-vinci status",
       "  da-vinci validate-assets",
       "  da-vinci audit [project-path]",
+      "  da-vinci preflight-pencil --ops-file <path>",
+      "  da-vinci ensure-pen --output <path>",
+      "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci check-pen-sync --pen <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci snapshot-pen --input <path> --output <path>",
+      "  da-vinci pencil-lock acquire --project <path>",
+      "  da-vinci pencil-lock release --project <path>",
+      "  da-vinci pencil-lock status",
+      "  da-vinci pencil-session begin --project <path> --pen <path>",
+      "  da-vinci pencil-session persist --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci pencil-session end --project <path> --pen <path> [--nodes-file <path>]",
+      "  da-vinci pencil-session status --project <path>",
       "  da-vinci --version",
       "",
       "Options:",
       "  --platform <value>   codex, claude, gemini, or all",
       "  --home <path>        override HOME for installation targets",
       "  --project <path>     override project path for audit",
+      "  --pen <path>         registered .pen path for sync checks",
+      "  --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"
+      "  --change <id>        scope completion audit to one change id",
+      "  --wait-ms <value>    wait for the global Pencil lock before failing",
+      "  --owner <value>      human-readable lock owner label",
+      "  --force              force a lock release held by another project"
     ].join("\n")
   );
 }
@@ -138,6 +184,315 @@ async function runCli(argv) {
     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 === "ensure-pen") {
+    const outputPath = getOption(argv, "--output");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!outputPath) {
+      throw new Error("`ensure-pen` requires `--output <path>`.");
+    }
+
+    const result = ensurePenFile({
+      outputPath,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`${result.created ? "Created" : "Verified existing"} .pen source at ${result.outputPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    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(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
+    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 === "check-pen-sync") {
+    const penPath = getOption(argv, "--pen");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+
+    if (!penPath || !nodesFile) {
+      throw new Error("`check-pen-sync` requires `--pen <path>` and `--nodes-file <path>`.");
+    }
+
+    const result = comparePenSync({
+      penPath,
+      nodesFile,
+      variablesFile,
+      version
+    });
+
+    if (!result.inSync) {
+      throw new Error(
+        [
+          "Registered `.pen` is out of sync with the provided live payload.",
+          `Pen: ${result.penPath}`,
+          `State file: ${result.statePath}`,
+          `Persisted hash: ${result.persistedHash}`,
+          `Live hash: ${result.liveHash}`
+        ].join("\n")
+      );
+    }
+
+    console.log(`Registered .pen is in sync: ${result.penPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.liveHash}`);
+    if (!result.usedStateFile) {
+      console.log("State file was missing; sync comparison fell back to hashing the disk .pen file directly.");
+    }
+    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(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
+    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 === "pencil-lock") {
+    const subcommand = getPositionalArgs(argv.slice(1), [
+      "--home",
+      "--project",
+      "--owner",
+      "--wait-ms"
+    ])[0];
+    const projectPath = getOption(argv, "--project") || process.cwd();
+    const owner = getOption(argv, "--owner");
+    const waitMs = getOption(argv, "--wait-ms");
+    const force = argv.includes("--force");
+
+    if (!subcommand || ["acquire", "release", "status"].includes(subcommand) === false) {
+      throw new Error("`pencil-lock` requires one of: acquire, release, status.");
+    }
+
+    if (subcommand === "acquire") {
+      const result = acquirePencilLock({
+        projectPath,
+        owner,
+        waitMs,
+        homeDir
+      });
+      console.log(`${result.alreadyHeld ? "Reused" : "Acquired"} Pencil lock at ${result.lockPath}`);
+      console.log(`Project: ${result.lock.projectPath}`);
+      console.log(`Owner: ${result.lock.owner}`);
+      return;
+    }
+
+    if (subcommand === "release") {
+      const result = releasePencilLock({
+        projectPath,
+        force,
+        homeDir
+      });
+      if (!result.hadLock) {
+        console.log(`No Pencil lock was present at ${result.lockPath}`);
+        return;
+      }
+      console.log(`Released Pencil lock at ${result.lockPath}`);
+      console.log(`Previous project: ${result.lock.projectPath}`);
+      return;
+    }
+
+    const result = getPencilLockStatus({ homeDir });
+    console.log(`Lock path: ${result.lockPath}`);
+    if (!result.lock) {
+      console.log("Status: unlocked");
+      return;
+    }
+    console.log("Status: locked");
+    console.log(`Project: ${result.lock.projectPath}`);
+    console.log(`Owner: ${result.lock.owner}`);
+    console.log(`PID: ${result.lock.pid}`);
+    return;
+  }
+
+  if (command === "pencil-session") {
+    const subcommand = getPositionalArgs(argv.slice(1), [
+      "--home",
+      "--project",
+      "--pen",
+      "--nodes-file",
+      "--variables-file",
+      "--version",
+      "--owner",
+      "--wait-ms"
+    ])[0];
+    const projectPath = getOption(argv, "--project") || process.cwd();
+    const penPath = getOption(argv, "--pen");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+    const owner = getOption(argv, "--owner");
+    const waitMs = getOption(argv, "--wait-ms");
+    const force = argv.includes("--force");
+
+    if (!subcommand || ["begin", "persist", "end", "status"].includes(subcommand) === false) {
+      throw new Error("`pencil-session` requires one of: begin, persist, end, status.");
+    }
+
+    if (subcommand === "begin") {
+      if (!penPath) {
+        throw new Error("`pencil-session begin` requires `--pen <path>`.");
+      }
+
+      const result = beginPencilSession({
+        projectPath,
+        penPath,
+        version,
+        verifyWithPencil,
+        owner,
+        waitMs,
+        homeDir
+      });
+
+      console.log(`Began Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+      return;
+    }
+
+    if (subcommand === "persist") {
+      if (!penPath || !nodesFile) {
+        throw new Error("`pencil-session persist` requires `--pen <path>` and `--nodes-file <path>`.");
+      }
+
+      const result = persistPencilSession({
+        projectPath,
+        penPath,
+        nodesFile,
+        variablesFile,
+        version,
+        verifyWithPencil,
+        homeDir
+      });
+
+      console.log(`Persisted Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+      console.log(`In sync: ${result.syncResult.inSync ? "yes" : "no"}`);
+      return;
+    }
+
+    if (subcommand === "end") {
+      if (!penPath) {
+        throw new Error("`pencil-session end` requires `--pen <path>`.");
+      }
+
+      const result = endPencilSession({
+        projectPath,
+        penPath,
+        nodesFile,
+        variablesFile,
+        version,
+        homeDir,
+        force
+      });
+
+      console.log(`Ended Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Final status: ${result.session.status}`);
+      if (result.syncResult) {
+        console.log(`Final sync verified: ${result.syncResult.inSync ? "yes" : "no"}`);
+      }
+      return;
+    }
+
+    const result = getPencilSessionStatus({
+      projectPath,
+      homeDir
+    });
+
+    console.log(`Project: ${result.projectRoot}`);
+    console.log(`Session state: ${result.sessionStatePath}`);
+    console.log(`Session status: ${result.session ? result.session.status : "missing"}`);
+    console.log(`Lock status: ${result.lockStatus.lock ? "locked" : "unlocked"}`);
+    if (result.session) {
+      console.log(`Pen path: ${result.session.penPath}`);
+      console.log(`Last persisted hash: ${result.session.lastPersistedHash || "(missing)"}`);
+    }
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 

package/lib/mcp-runtime-gate.js

@@ -52,6 +52,10 @@ function resolveProjectPath(projectRoot, targetPath) {
   return path.normalize(path.resolve(projectRoot, targetPath));
 }
 
+function normalizeHash(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
 function isUnnamedEditor(activeEditor) {
   const normalized = normalizeEditorName(activeEditor).toLowerCase();
   return normalized === "" || normalized === "new";
@@ -91,12 +95,17 @@ function derivePhase(snapshot) {
 
 function evaluateSourceConvergence(snapshot) {
   const notes = [];
+  const phase = derivePhase(snapshot);
   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);
+  const usedEmptyFilePath = Boolean(snapshot.usedEmptyFilePath);
+  const penSyncVerified = snapshot.penSyncVerified === true;
+  const liveSnapshotHash = normalizeHash(snapshot.liveSnapshotHash);
+  const persistedSnapshotHash = normalizeHash(snapshot.persistedSnapshotHash);
 
   if (Boolean(snapshot.mcpAvailable) === false) {
     return {
@@ -119,6 +128,13 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (usedEmptyFilePath) {
+    return {
+      status: BLOCK,
+      notes: ["Pencil operations used an empty `filePath` even though the workflow has a registered project-local `.pen` source."]
+    };
+  }
+
   if (!shellVisiblePenExists) {
     return {
       status: BLOCK,
@@ -142,6 +158,29 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (phase === "completion") {
+    if (!penSyncVerified) {
+      return {
+        status: BLOCK,
+        notes: ["No explicit live-to-disk `.pen` sync verification was recorded before completion."]
+      };
+    }
+
+    if (!liveSnapshotHash || !persistedSnapshotHash) {
+      return {
+        status: BLOCK,
+        notes: ["Completion requires both live and persisted `.pen` snapshot hashes."]
+      };
+    }
+
+    if (liveSnapshotHash !== persistedSnapshotHash) {
+      return {
+        status: BLOCK,
+        notes: ["Current live Pencil snapshot does not match the last persisted `.pen` snapshot."]
+      };
+    }
+  }
+
   if (noNewPencilEditsYet) {
     notes.push("No new Pencil edits were recorded yet; source convergence is only provisionally confirmed.");
     return {
@@ -150,9 +189,16 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (penSyncVerified) {
+    notes.push("Live Pencil snapshot was explicitly verified against the persisted project-local `.pen` source.");
+  }
+
   return {
     status: PASS,
-    notes: ["Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk."]
+    notes: [
+      "Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk.",
+      ...notes
+    ]
   };
 }
 
@@ -296,6 +342,9 @@ function evaluateMcpRuntimeGate(snapshot = {}) {
     shellVisiblePenPath:
       typeof snapshot.shellVisiblePenPath === "string" ? snapshot.shellVisiblePenPath.trim() : "",
     shellVisiblePenExists: Boolean(snapshot.shellVisiblePenExists),
+    penSyncVerified: snapshot.penSyncVerified === true,
+    liveSnapshotHash: normalizeHash(snapshot.liveSnapshotHash),
+    persistedSnapshotHash: normalizeHash(snapshot.persistedSnapshotHash),
     claimedAnchorIds: normalizeArray(snapshot.claimedAnchorIds),
     claimedReviewedScreenIds: normalizeArray(snapshot.claimedReviewedScreenIds),
     reviewTargets: normalizeArray(snapshot.reviewTargets),
@@ -320,6 +369,9 @@ function formatMcpRuntimeGateSection(snapshot, result, options = {}) {
     `- Registered \`.pen\` path: ${result.registeredPenPath || "(missing)"}`,
     `- Shell-visible \`.pen\` path: ${result.shellVisiblePenPath || "(missing)"}`,
     `- Shell-visible \`.pen\` exists: ${result.shellVisiblePenExists ? "yes" : "no"}`,
+    `- Pen sync verified: ${result.penSyncVerified ? "yes" : "no"}`,
+    `- Live snapshot hash: ${result.liveSnapshotHash || "(missing)"}`,
+    `- Persisted snapshot hash: ${result.persistedSnapshotHash || "(missing)"}`,
     `- 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)"}`,