@xenonbyte/da-vinci-workflow 0.1.15 → 0.1.17

package/lib/pen-persistence.js

@@ -0,0 +1,515 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { spawnSync } = require("child_process");
+
+const DEFAULT_PEN_VERSION = "2.9";
+const DEFAULT_READ_DEPTH = 50;
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function extractFirstJson(text) {
+  const source = String(text || "");
+  const decoder = new JSONDecoder();
+  return decoder.decodeFirst(source);
+}
+
+class JSONDecoder {
+  constructor() {
+    this.decoder = JSON;
+  }
+
+  decodeFirst(text) {
+    for (let index = 0; index < text.length; index += 1) {
+      const ch = text[index];
+      if (ch !== "{" && ch !== "[") {
+        continue;
+      }
+
+      try {
+        const { value } = this.rawDecode(text.slice(index));
+        return value;
+      } catch (error) {
+        continue;
+      }
+    }
+
+    throw new Error("No JSON payload found.");
+  }
+
+  rawDecode(text) {
+    let end = 0;
+    let inString = false;
+    let escape = false;
+    let depth = 0;
+    const opening = text[0];
+    const closing = opening === "{" ? "}" : "]";
+
+    for (let index = 0; index < text.length; index += 1) {
+      const ch = text[index];
+
+      if (inString) {
+        if (escape) {
+          escape = false;
+        } else if (ch === "\\") {
+          escape = true;
+        } else if (ch === "\"") {
+          inString = false;
+        }
+        continue;
+      }
+
+      if (ch === "\"") {
+        inString = true;
+        continue;
+      }
+
+      if (ch === opening) {
+        depth += 1;
+      } else if (ch === closing) {
+        depth -= 1;
+        if (depth === 0) {
+          end = index + 1;
+          break;
+        }
+      }
+    }
+
+    if (end === 0) {
+      throw new Error("Incomplete JSON payload.");
+    }
+
+    return {
+      value: JSON.parse(text.slice(0, end)),
+      end
+    };
+  }
+}
+
+function readJsonPayload(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    return extractFirstJson(raw);
+  }
+}
+
+function hasTruncatedChildren(value) {
+  if (Array.isArray(value)) {
+    return value.some((item) => hasTruncatedChildren(item));
+  }
+
+  if (!isPlainObject(value)) {
+    return value === "...";
+  }
+
+  return Object.values(value).some((item) => hasTruncatedChildren(item));
+}
+
+function normalizeNodesPayload(payload) {
+  const nodes = getNodesArray(payload);
+
+  if (!nodes) {
+    throw new Error("Nodes payload must be an array or an object with a `nodes` array.");
+  }
+
+  if (hasTruncatedChildren(nodes)) {
+    throw new Error("Nodes payload is truncated (`...`). Re-read the live document with a deeper batch_get before persisting.");
+  }
+
+  return nodes;
+}
+
+function getNodesArray(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  if (payload && Array.isArray(payload.nodes)) {
+    return payload.nodes;
+  }
+
+  return null;
+}
+
+function normalizeVariablesPayload(payload) {
+  if (!payload) {
+    return undefined;
+  }
+
+  if (isPlainObject(payload.variables)) {
+    return payload.variables;
+  }
+
+  if (isPlainObject(payload)) {
+    return payload;
+  }
+
+  throw new Error("Variables payload must be an object or an object with a `variables` key.");
+}
+
+function canonicalizeJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalizeJson(item));
+  }
+
+  if (!isPlainObject(value)) {
+    return value;
+  }
+
+  return Object.keys(value)
+    .sort()
+    .reduce((accumulator, key) => {
+      accumulator[key] = canonicalizeJson(value[key]);
+      return accumulator;
+    }, {});
+}
+
+function buildPenDocument({ version = DEFAULT_PEN_VERSION, nodes, variables }) {
+  const document = {
+    version,
+    children: normalizeNodesPayload(nodes)
+  };
+
+  const normalizedVariables = normalizeVariablesPayload(variables);
+  if (normalizedVariables && Object.keys(normalizedVariables).length > 0) {
+    document.variables = normalizedVariables;
+  }
+
+  return document;
+}
+
+function hashPenDocument(document) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonicalizeJson(document)))
+    .digest("hex");
+}
+
+function getStandardPenStatePath(outputPath) {
+  const targetPath = path.resolve(outputPath);
+  const marker = `${path.sep}.da-vinci${path.sep}designs${path.sep}`;
+  const markerIndex = targetPath.indexOf(marker);
+
+  if (markerIndex < 0) {
+    return `${targetPath}.meta.json`;
+  }
+
+  const projectRoot = targetPath.slice(0, markerIndex);
+  const relativePenPath = targetPath.slice(markerIndex + marker.length);
+  const stateFileName = `${relativePenPath.split(path.sep).join("__")}.json`;
+  return path.join(projectRoot, ".da-vinci", "state", "pens", stateFileName);
+}
+
+function writePenDocumentAtomic(outputPath, document) {
+  const targetPath = path.resolve(outputPath);
+  const targetDir = path.dirname(targetPath);
+  const tempPath = path.join(
+    targetDir,
+    `.${path.basename(targetPath)}.tmp-${process.pid}-${Date.now()}`
+  );
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.writeFileSync(tempPath, JSON.stringify(document, null, 2) + "\n", "utf8");
+  fs.renameSync(tempPath, targetPath);
+  return targetPath;
+}
+
+function writeJsonFileAtomic(outputPath, payload) {
+  const targetPath = path.resolve(outputPath);
+  const targetDir = path.dirname(targetPath);
+  const tempPath = path.join(
+    targetDir,
+    `.${path.basename(targetPath)}.tmp-${process.pid}-${Date.now()}`
+  );
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  fs.renameSync(tempPath, targetPath);
+  return targetPath;
+}
+
+function buildPenState(outputPath, document, options = {}) {
+  return {
+    schema: 1,
+    source: options.source || "write-pen",
+    penPath: path.resolve(outputPath),
+    version: document.version || DEFAULT_PEN_VERSION,
+    snapshotHash: hashPenDocument(document),
+    topLevelIds: Array.isArray(document.children) ? document.children.map((node) => node.id) : [],
+    topLevelCount: Array.isArray(document.children) ? document.children.length : 0,
+    persistedAt: options.persistedAt || new Date().toISOString()
+  };
+}
+
+function writePenStateAtomic(outputPath, state) {
+  const statePath = getStandardPenStatePath(outputPath);
+  writeJsonFileAtomic(statePath, state);
+  return statePath;
+}
+
+function readPenState(outputPath) {
+  const statePath = getStandardPenStatePath(outputPath);
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+  return readJsonPayload(statePath);
+}
+
+function runPencilInteractive(inputPath, commands, options = {}) {
+  const pencilBin = options.pencilBin || "pencil";
+  const unusedOutput = path.join(
+    os.tmpdir(),
+    `da-vinci-verify-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.pen`
+  );
+  const payload = Array.isArray(commands) ? commands.join("\n") : String(commands || "");
+  const result = spawnSync(
+    pencilBin,
+    ["interactive", "-i", path.resolve(inputPath), "-o", unusedOutput],
+    {
+      input: `${payload}\nexit()\n`,
+      encoding: "utf8",
+      maxBuffer: 8 * 1024 * 1024
+    }
+  );
+
+  fs.rmSync(unusedOutput, { force: true });
+
+  const stdout = result.stdout || "";
+  const stderr = result.stderr || "";
+  if (result.status !== 0) {
+    throw new Error(
+      `Pencil interactive failed for ${inputPath}.\n${stdout}${stderr}`.trim()
+    );
+  }
+
+  return `${stdout}${stderr}`;
+}
+
+function verifyPenFileWithPencil(filePath, options = {}) {
+  const output = runPencilInteractive(filePath, ['batch_get({ readDepth: 1 })'], options);
+  const payload = extractFirstJson(output);
+  const nodes = getNodesArray(payload);
+  const expectedTopLevelIds = options.expectedTopLevelIds || [];
+
+  if (!nodes) {
+    throw new Error("Pencil reopen verification did not return a `nodes` array.");
+  }
+
+  if (expectedTopLevelIds.length > 0) {
+    const actualIds = nodes.map((node) => node.id);
+    if (JSON.stringify(actualIds) !== JSON.stringify(expectedTopLevelIds)) {
+      throw new Error(
+        `Reopened .pen file top-level ids do not match. Expected ${expectedTopLevelIds.join(", ")}, got ${actualIds.join(", ")}.`
+      );
+    }
+  }
+
+  return {
+    topLevelCount: nodes.length,
+    topLevelIds: nodes.map((node) => node.id)
+  };
+}
+
+function writePenFromPayloadFiles(options) {
+  const outputPath = path.resolve(options.outputPath);
+  const nodes = readJsonPayload(options.nodesFile);
+  const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
+  const document = buildPenDocument({
+    version: options.version || DEFAULT_PEN_VERSION,
+    nodes,
+    variables
+  });
+
+  writePenDocumentAtomic(outputPath, document);
+  const state = buildPenState(outputPath, document, { source: "write-pen" });
+  const statePath = writePenStateAtomic(outputPath, state);
+
+  const verification = options.verifyWithPencil
+    ? verifyPenFileWithPencil(outputPath, {
+        pencilBin: options.pencilBin,
+        expectedTopLevelIds: document.children.map((node) => node.id)
+      })
+    : null;
+
+  return {
+    outputPath,
+    document,
+    verification,
+    state,
+    statePath
+  };
+}
+
+function readPenVersion(inputPath) {
+  const payload = JSON.parse(fs.readFileSync(inputPath, "utf8"));
+  return payload.version || DEFAULT_PEN_VERSION;
+}
+
+function capturePenSnapshot(inputPath, options = {}) {
+  const readDepth = options.readDepth || DEFAULT_READ_DEPTH;
+  const nodesOutput = runPencilInteractive(
+    inputPath,
+    [
+      `batch_get({ readDepth: ${readDepth}, includePathGeometry: true, resolveInstances: false, resolveVariables: false })`
+    ],
+    options
+  );
+  const variablesOutput = runPencilInteractive(inputPath, ["get_variables()"], options);
+
+  return {
+    nodes: normalizeNodesPayload(extractFirstJson(nodesOutput)),
+    variables: normalizeVariablesPayload(extractFirstJson(variablesOutput))
+  };
+}
+
+function snapshotPenFile(options) {
+  const inputPath = path.resolve(options.inputPath);
+  const outputPath = path.resolve(options.outputPath);
+  const snapshot = capturePenSnapshot(inputPath, options);
+  const document = buildPenDocument({
+    version: options.version || readPenVersion(inputPath),
+    nodes: snapshot.nodes,
+    variables: snapshot.variables
+  });
+
+  writePenDocumentAtomic(outputPath, document);
+  const state = buildPenState(outputPath, document, { source: "snapshot-pen" });
+  const statePath = writePenStateAtomic(outputPath, state);
+
+  const verification = options.verifyWithPencil
+    ? verifyPenFileWithPencil(outputPath, {
+        pencilBin: options.pencilBin,
+        expectedTopLevelIds: document.children.map((node) => node.id)
+      })
+    : null;
+
+  return {
+    inputPath,
+    outputPath,
+    document,
+    verification,
+    state,
+    statePath
+  };
+}
+
+function readPenDocument(inputPath) {
+  return readJsonPayload(inputPath);
+}
+
+function ensurePenFile(options) {
+  const outputPath = path.resolve(options.outputPath);
+  const exists = fs.existsSync(outputPath);
+  let document;
+  let created = false;
+
+  if (exists) {
+    document = readPenDocument(outputPath);
+    if (!Array.isArray(document.children)) {
+      throw new Error(`Existing .pen file is invalid or missing \`children\`: ${outputPath}`);
+    }
+  } else {
+    document = buildPenDocument({
+      version: options.version || DEFAULT_PEN_VERSION,
+      nodes: { nodes: [] },
+      variables: {}
+    });
+    writePenDocumentAtomic(outputPath, document);
+    created = true;
+  }
+
+  const state = buildPenState(outputPath, document, {
+    source: created ? "ensure-pen:create" : "ensure-pen:existing"
+  });
+  const statePath = writePenStateAtomic(outputPath, state);
+
+  const verification = options.verifyWithPencil
+    ? verifyPenFileWithPencil(outputPath, {
+        pencilBin: options.pencilBin,
+        expectedTopLevelIds: document.children.map((node) => node.id)
+      })
+    : null;
+
+  return {
+    outputPath,
+    created,
+    document,
+    verification,
+    state,
+    statePath
+  };
+}
+
+function hashPayloadFiles(options) {
+  const nodes = readJsonPayload(options.nodesFile);
+  const variables = options.variablesFile ? readJsonPayload(options.variablesFile) : undefined;
+  const document = buildPenDocument({
+    version: options.version || DEFAULT_PEN_VERSION,
+    nodes,
+    variables
+  });
+
+  return {
+    document,
+    snapshotHash: hashPenDocument(document)
+  };
+}
+
+function comparePenSync(options) {
+  const penPath = path.resolve(options.penPath);
+  if (!fs.existsSync(penPath)) {
+    throw new Error(`Registered .pen file does not exist: ${penPath}`);
+  }
+
+  const persistedDocument = readPenDocument(penPath);
+  const live = hashPayloadFiles({
+    ...options,
+    version: options.version || persistedDocument.version || DEFAULT_PEN_VERSION
+  });
+  const persistedState = readPenState(penPath);
+  const persistedHash = persistedState && persistedState.snapshotHash
+    ? String(persistedState.snapshotHash)
+    : hashPenDocument(persistedDocument);
+
+  return {
+    penPath,
+    statePath: getStandardPenStatePath(penPath),
+    persistedHash,
+    liveHash: live.snapshotHash,
+    inSync: persistedHash === live.snapshotHash,
+    usedStateFile: Boolean(persistedState && persistedState.snapshotHash),
+    state: persistedState
+  };
+}
+
+module.exports = {
+  DEFAULT_PEN_VERSION,
+  DEFAULT_READ_DEPTH,
+  extractFirstJson,
+  readJsonPayload,
+  normalizeNodesPayload,
+  normalizeVariablesPayload,
+  canonicalizeJson,
+  buildPenDocument,
+  hashPenDocument,
+  getStandardPenStatePath,
+  writePenDocumentAtomic,
+  writeJsonFileAtomic,
+  buildPenState,
+  writePenStateAtomic,
+  readPenState,
+  runPencilInteractive,
+  verifyPenFileWithPencil,
+  writePenFromPayloadFiles,
+  capturePenSnapshot,
+  snapshotPenFile,
+  readPenDocument,
+  ensurePenFile,
+  hashPayloadFiles,
+  comparePenSync
+};

package/lib/pencil-lock.js

@@ -0,0 +1,128 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function getLockPath(options = {}) {
+  const homeDir = options.homeDir ? path.resolve(options.homeDir) : os.homedir();
+  return path.join(homeDir, ".da-vinci", "pencil-mcp.lock");
+}
+
+function readLock(lockPath) {
+  const resolvedLockPath = path.resolve(lockPath);
+  if (!fs.existsSync(resolvedLockPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(resolvedLockPath, "utf8"));
+}
+
+function writeLock(lockPath, payload) {
+  const resolvedLockPath = path.resolve(lockPath);
+  fs.mkdirSync(path.dirname(resolvedLockPath), { recursive: true });
+  const handle = fs.openSync(resolvedLockPath, "wx");
+
+  try {
+    fs.writeFileSync(handle, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function acquirePencilLock(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const owner = options.owner || path.basename(projectPath);
+  const waitMs = Number.isFinite(Number(options.waitMs)) ? Number(options.waitMs) : 0;
+  const pollIntervalMs = Math.max(50, Number(options.pollIntervalMs) || 100);
+  const lockPath = getLockPath(options);
+  const deadline = Date.now() + Math.max(0, waitMs);
+  const payload = {
+    schema: 1,
+    projectPath,
+    owner,
+    pid: process.pid,
+    acquiredAt: new Date().toISOString()
+  };
+
+  while (true) {
+    try {
+      writeLock(lockPath, payload);
+      return {
+        lockPath,
+        acquired: true,
+        alreadyHeld: false,
+        lock: payload
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+
+      const current = readLock(lockPath);
+      if (current && current.projectPath === projectPath) {
+        return {
+          lockPath,
+          acquired: true,
+          alreadyHeld: true,
+          lock: current
+        };
+      }
+
+      if (Date.now() >= deadline) {
+        const holder = current
+          ? `${current.projectPath} (owner: ${current.owner || "unknown"}, pid: ${current.pid || "unknown"})`
+          : "unknown holder";
+        throw new Error(`Pencil MCP lock is already held by ${holder}.`);
+      }
+
+      const sleepUntil = Date.now() + pollIntervalMs;
+      while (Date.now() < sleepUntil) {
+        // Busy wait to keep the CLI synchronous without additional runtime dependencies.
+      }
+    }
+  }
+}
+
+function releasePencilLock(options = {}) {
+  const projectPath = options.projectPath ? path.resolve(options.projectPath) : "";
+  const lockPath = getLockPath(options);
+  const current = readLock(lockPath);
+
+  if (!current) {
+    return {
+      lockPath,
+      released: false,
+      hadLock: false,
+      lock: null
+    };
+  }
+
+  if (projectPath && current.projectPath !== projectPath && !options.force) {
+    throw new Error(
+      `Pencil MCP lock is held by a different project: ${current.projectPath}`
+    );
+  }
+
+  fs.rmSync(lockPath, { force: true });
+  return {
+    lockPath,
+    released: true,
+    hadLock: true,
+    lock: current
+  };
+}
+
+function getPencilLockStatus(options = {}) {
+  const lockPath = getLockPath(options);
+  return {
+    lockPath,
+    lock: readLock(lockPath)
+  };
+}
+
+module.exports = {
+  getLockPath,
+  readLock,
+  acquirePencilLock,
+  releasePencilLock,
+  getPencilLockStatus
+};