@xenonbyte/da-vinci-workflow 0.1.24 → 0.1.26

package/lib/workflow-bootstrap.js

@@ -0,0 +1,255 @@
+const fs = require("fs");
+const path = require("path");
+
+const { isPathInside } = require("./fs-safety");
+const { ensurePenFile } = require("./pen-persistence");
+const { pathExists, readTextIfExists, writeFileAtomic } = require("./utils");
+
+const DEFAULT_PROJECT_PEN_RELATIVE_PATH = ".da-vinci/designs/project-baseline.pen";
+
+function validateChangeId(changeId) {
+  const normalized = String(changeId || "").trim();
+  if (!normalized) {
+    return "";
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(normalized)) {
+    throw new Error(
+      `Invalid change id: ${normalized}. Use letters, numbers, dot, underscore, or dash.`
+    );
+  }
+  return normalized;
+}
+
+function extractRegisteredPenPath(projectRoot, registryText) {
+  const matches = String(registryText || "").match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
+  for (const relativePath of matches) {
+    const resolvedPath = path.resolve(projectRoot, relativePath);
+    if (isPathInside(projectRoot, resolvedPath)) {
+      return resolvedPath;
+    }
+  }
+  return "";
+}
+
+function buildProjectTemplates(preferredPenRelativePath) {
+  return {
+    "DA-VINCI.md": [
+      "# DA-VINCI",
+      "",
+      "## Product Surface",
+      "- TODO",
+      "",
+      "## Visual Direction",
+      "- TODO",
+      "",
+      "## Visual Assist",
+      "- Preferred adapters:",
+      "- Fallback:",
+      "  - native",
+      "",
+      "## Source Of Truth",
+      "- requirements",
+      "- project-local Pencil source",
+      ""
+    ].join("\n"),
+    ".da-vinci/project-inventory.md": [
+      "# Project Inventory",
+      "",
+      "## Current Product",
+      "- TODO",
+      "",
+      "## Routes And Pages",
+      "- TODO",
+      ""
+    ].join("\n"),
+    ".da-vinci/page-map.md": [
+      "# Page Map",
+      "",
+      "## Canonical Pages",
+      "- TODO",
+      "",
+      "## Shared Regions",
+      "- TODO",
+      ""
+    ].join("\n"),
+    ".da-vinci/design-registry.md": [
+      "# Design Registry",
+      "",
+      "## Preferred Project-local Source",
+      `- Preferred .pen: ${preferredPenRelativePath}`,
+      ""
+    ].join("\n")
+  };
+}
+
+function buildChangeTemplates(changeId) {
+  const changePrefix = `.da-vinci/changes/${changeId}`;
+  return {
+    [`${changePrefix}/design-brief.md`]: [
+      "# Design Brief",
+      "",
+      "## Product Form Factor",
+      "- TODO",
+      "",
+      "## Visual Direction",
+      "- TODO",
+      ""
+    ].join("\n"),
+    [`${changePrefix}/design.md`]: [
+      "# Design",
+      "",
+      "## Goals",
+      "- TODO",
+      "",
+      "## Anchor Surfaces",
+      "- TODO",
+      ""
+    ].join("\n"),
+    [`${changePrefix}/pencil-design.md`]: [
+      "# Pencil Design",
+      "",
+      "## Screenshot Review Records",
+      "- TODO",
+      "",
+      "## Checkpoint Status",
+      "- Design checkpoint: `WARN`",
+      ""
+    ].join("\n"),
+    [`${changePrefix}/pencil-bindings.md`]: [
+      "# Pencil Bindings",
+      "",
+      "## Bound Pages",
+      "- TODO",
+      ""
+    ].join("\n")
+  };
+}
+
+function writeScaffoldFile(projectRoot, relativePath, content, force, result) {
+  const absolutePath = path.join(projectRoot, relativePath);
+  if (pathExists(absolutePath)) {
+    if (!force) {
+      result.skipped.push(relativePath);
+      return;
+    }
+    writeFileAtomic(absolutePath, content);
+    result.overwritten.push(relativePath);
+    return;
+  }
+
+  writeFileAtomic(absolutePath, content);
+  result.created.push(relativePath);
+}
+
+function bootstrapProjectArtifacts(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const changeId = validateChangeId(options.changeId);
+  const force = options.force === true;
+
+  fs.mkdirSync(projectRoot, { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, ".da-vinci", "designs"), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, ".da-vinci", "changes"), { recursive: true });
+
+  const existingRegistryText = readTextIfExists(path.join(projectRoot, ".da-vinci", "design-registry.md"));
+  const registeredPenPath = extractRegisteredPenPath(projectRoot, existingRegistryText);
+  const preferredPenPath = registeredPenPath || path.join(projectRoot, DEFAULT_PROJECT_PEN_RELATIVE_PATH);
+  const preferredPenRelativePath = path.relative(projectRoot, preferredPenPath) || DEFAULT_PROJECT_PEN_RELATIVE_PATH;
+
+  const result = {
+    projectRoot,
+    changeId: changeId || null,
+    created: [],
+    overwritten: [],
+    skipped: [],
+    penPath: preferredPenPath,
+    penRelativePath: preferredPenRelativePath,
+    changeArtifactsCreated: Boolean(changeId),
+    registryUpdatedToPreferredPen: Boolean(registeredPenPath) || !pathExists(path.join(projectRoot, ".da-vinci", "design-registry.md"))
+  };
+
+  const projectTemplates = buildProjectTemplates(preferredPenRelativePath);
+  for (const [relativePath, content] of Object.entries(projectTemplates)) {
+    writeScaffoldFile(projectRoot, relativePath, content, force, result);
+  }
+
+  if (changeId) {
+    const changeTemplates = buildChangeTemplates(changeId);
+    for (const [relativePath, content] of Object.entries(changeTemplates)) {
+      writeScaffoldFile(projectRoot, relativePath, content, force, result);
+    }
+  }
+
+  const penResult = ensurePenFile({
+    outputPath: preferredPenPath
+  });
+  result.pen = {
+    path: penResult.outputPath,
+    relativePath: preferredPenRelativePath,
+    created: penResult.created,
+    statePath: penResult.statePath,
+    snapshotHash: penResult.state.snapshotHash
+  };
+
+  if (!registeredPenPath && pathExists(path.join(projectRoot, ".da-vinci", "design-registry.md")) && !force) {
+    const currentRegistryText = readTextIfExists(path.join(projectRoot, ".da-vinci", "design-registry.md"));
+    result.registryUpdatedToPreferredPen = currentRegistryText.includes(preferredPenRelativePath);
+  }
+
+  return result;
+}
+
+function formatBootstrapProjectReport(result) {
+  const lines = [
+    "Da Vinci bootstrap-project",
+    `Project: ${result.projectRoot}`,
+    `Project-local .pen: ${result.pen.relativePath} (${result.pen.created ? "created" : "verified existing"})`,
+    `State file: ${result.pen.statePath}`
+  ];
+
+  if (result.changeId) {
+    lines.push(`Change scaffold: .da-vinci/changes/${result.changeId}/`);
+  } else {
+    lines.push("Change scaffold: skipped (pass `--change <change-id>` to create change-level artifacts)");
+  }
+
+  if (result.created.length > 0) {
+    lines.push("", "Created:");
+    for (const relativePath of result.created) {
+      lines.push(`- ${relativePath}`);
+    }
+  }
+
+  if (result.overwritten.length > 0) {
+    lines.push("", "Overwritten:");
+    for (const relativePath of result.overwritten) {
+      lines.push(`- ${relativePath}`);
+    }
+  }
+
+  if (result.skipped.length > 0) {
+    lines.push("", "Preserved existing:");
+    for (const relativePath of result.skipped) {
+      lines.push(`- ${relativePath}`);
+    }
+  }
+
+  lines.push("", "Next steps:");
+  if (!result.changeId) {
+    lines.push(`- scaffold change artifacts with: da-vinci bootstrap-project --project ${result.projectRoot} --change <change-id>`);
+  }
+  lines.push(`- begin a Pencil session with: da-vinci pencil-session begin --project ${result.projectRoot} --pen ${result.pen.path}`);
+  lines.push(`- after the first persisted write, run: da-vinci audit --mode integrity ${result.projectRoot}`);
+  if (!result.registryUpdatedToPreferredPen) {
+    lines.push(
+      `- update .da-vinci/design-registry.md to reference ${result.pen.relativePath}, or rerun bootstrap-project with --force`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  DEFAULT_PROJECT_PEN_RELATIVE_PATH,
+  bootstrapProjectArtifacts,
+  formatBootstrapProjectReport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js",
@@ -18,14 +18,19 @@
     "examples",
     "bin",
     "lib",
-    "scripts"
+    "scripts/postinstall.js",
+    "scripts/validate-assets.js"
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "validate-assets": "node scripts/validate-assets.js",
+    "test": "node scripts/run-tests.js",
+    "test:audit-parsers": "node scripts/test-audit-parsers.js",
     "test:audit-safety": "node scripts/test-audit-safety.js",
     "test:audit-context-delta": "node scripts/test-audit-context-delta.js",
     "test:audit-design-supervisor": "node scripts/test-audit-design-supervisor.js",
+    "test:bootstrap-project": "node scripts/test-bootstrap-project.js",
+    "test:doc-release-alignment": "node scripts/test-doc-release-alignment.js",
     "test:pencil-lock": "node scripts/test-pencil-lock.js",
     "test:mode-consistency": "node scripts/test-mode-consistency.js",
     "test:mcp-runtime-gate": "node scripts/test-mcp-runtime-gate.js",
@@ -37,7 +42,12 @@
     "test:icon-sync": "node scripts/test-icon-sync.js",
     "test:icon-aliases": "node scripts/test-icon-aliases.js",
     "test:supervisor-review-cli": "node scripts/test-supervisor-review-cli.js",
-    "test:supervisor-review-integration": "node scripts/test-supervisor-review-integration.js"
+    "test:supervisor-review-integration": "node scripts/test-supervisor-review-integration.js",
+    "test:install": "node scripts/test-install.js",
+    "test:package-contents": "node scripts/test-package-contents.js",
+    "quality:ci:core": "npm run test",
+    "quality:reviewer-bridge-smoke": "npm run test:supervisor-review-integration",
+    "quality:ci": "npm run quality:ci:core"
   },
   "engines": {
     "node": ">=18"

package/references/artifact-templates.md

@@ -569,6 +569,7 @@ Use this structure:
 - Revision outcome
 - Whether broad expansion is approved
 - Whether implementation-task handoff is approved
+- Keep one canonical structured supervisor-review section; avoid ad-hoc headings such as `## Design-Supervisor Review (Round X Attempt)`
 
 ## Anchor Surfaces
 - Which 1-3 anchor screens were designed first

package/references/checkpoints.md

@@ -199,6 +199,7 @@ Check:
 - the active editor is not still an unnamed live document such as `new`
 - the workflow did not keep using an empty `filePath` after a registered `.pen` existed
 - the active editor, registered project-local `.pen` path, and shell-visible `.pen` file are converged strongly enough to trust the runtime source
+- when external or secondary `.pen` sources exist, their hashes have been reconciled against the project-local `.pen` baseline before new edits continue
 - completion-stage runtime evidence includes an explicit live-to-disk sync verification for the registered `.pen`
 - claimed anchor ids exist in the active live editor
 - claimed reviewed screens and screenshot targets exist in the active live editor
@@ -231,6 +232,7 @@ Check:
 - the preferred `.pen` path in `design-registry.md` is workflow-owned and specific, not hand-wavy
 - the active Pencil editor path matches the preferred project-local `.pen` path, or the project-local file has been reconstructed explicitly
 - the preferred project-local `.pen` file exists as a shell-visible file when the workflow created or edited Pencil work
+- if external or secondary `.pen` files exist, the workflow records baseline hash alignment and explicit source-priority confirmation before the next edit round
 - exported screenshots are treated only as review artifacts, not as page-to-design source of truth
 - each implementation page has a Pencil page or an explicit exception
 - shared layouts and shared regions are bound clearly enough to implement from

package/references/design-inputs.md

@@ -20,6 +20,7 @@ The preferred `.pen` path in `design-registry.md` is workflow-owned state.
 - it should be generated and maintained by Da Vinci
 - it should not rely on the user manually typing a path into `design-registry.md`
 - external references may influence source priority, but the project-local path should still be resolved explicitly
+- in multi-source scenarios, a successful `pencil-session persist` confirms only live-vs-project sync for that run; verify cross-source hash alignment before treating the project file as globally latest
 
 Use these defaults:
 
@@ -32,6 +33,7 @@ Before broad Pencil work begins:
 - resolve the exact project-local path
 - record that path in `design-registry.md`
 - treat that path as the required target for the active design pass
+- if external or secondary `.pen` sources exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`; when hashes diverge, confirm source priority and sync the chosen source into `<project-pen>` before new edits
 
 If Pencil MCP is currently pointing at a different active editor:
 

package/references/pencil-design-to-code.md

@@ -75,6 +75,7 @@ When generating or editing Pencil data:
 - if unsupported-property rollbacks repeat on the same anchor surface, stop treating that pass as stable forward progress until the schema usage is corrected
 - after any rolled-back batch or structure-changing edit, refresh the live node structure before descendant-targeted follow-up operations
 - before the first Pencil edit on a redesign pass, require `da-vinci pencil-session begin --project <project-path> --pen <path>` whenever the session wrapper is available so the registered project-local `.pen` exists before editing and the global lock is held; use `da-vinci ensure-pen --output <path> --verify-open` only as a lower-level fallback when the session wrapper truly cannot be used
+- if external or secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before the new write phase; if hashes diverge, confirm source priority and sync the chosen source into `<project-pen>` before new edits
 - acquire the global Pencil lock before MCP write operations when multiple redesign sessions could overlap on the same machine
 - on autonomous runs, require the higher-level wrapper:
   `da-vinci pencil-session begin`
@@ -85,6 +86,7 @@ When generating or editing Pencil data:
 - if a registered project-local `.pen` already existed, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
 - use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` when you already have MCP-readable snapshot payloads and need an atomic project-local `.pen` write
 - run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` after material live edits and before completion claims to prove the live snapshot matches the persisted `.pen`
+- when an external source is selected as latest, use `da-vinci sync-pen-source --from <preferred-source.pen> --to <project-pen>` to materialize it into the project-local baseline before reopening a write session
 - use `da-vinci snapshot-pen --input <path> --output <path> --verify-open` only as a disk-to-disk utility when you need to re-canonicalize an existing `.pen`; it is not a substitute for persisting the current live editor
 - completion audit expects `.da-vinci/state/pencil-session.json` to exist and reflect the latest persisted `.pen` hash
 - keep workflow markdown out of `.da-vinci/designs/`; reserve that directory for `.pen` files only

package/scripts/fixtures/complex-sample.pen

@@ -1,295 +0,0 @@
-{
-  "version": "2.9",
-  "variables": {
-    "surface-bg": {
-      "type": "color",
-      "value": "#F4EFE7"
-    },
-    "surface-panel": {
-      "type": "color",
-      "value": "#FFFDF8"
-    },
-    "surface-border": {
-      "type": "color",
-      "value": "#D7CCBC"
-    },
-    "deck-fill": {
-      "type": "color",
-      "value": "#17304A"
-    },
-    "deck-fill-deep": {
-      "type": "color",
-      "value": "#10263A"
-    },
-    "surface-ink": {
-      "type": "color",
-      "value": "#132033"
-    },
-    "surface-muted": {
-      "type": "color",
-      "value": "#5D6673"
-    },
-    "accent-amber": {
-      "type": "color",
-      "value": "#C98A2B"
-    }
-  },
-  "children": [
-    {
-      "type": "frame",
-      "id": "healthy",
-      "x": 0,
-      "y": 0,
-      "name": "Diagnostics Console / Healthy",
-      "width": 420,
-      "fill": "$surface-bg",
-      "layout": "vertical",
-      "gap": 18,
-      "padding": [
-        18,
-        18,
-        24,
-        18
-      ],
-      "children": [
-        {
-          "type": "frame",
-          "id": "deckHealthy",
-          "name": "Command Deck",
-          "width": "fill_container",
-          "fill": [
-            {
-              "type": "gradient",
-              "gradientType": "linear",
-              "enabled": true,
-              "rotation": 180,
-              "size": {
-                "height": 1
-              },
-              "colors": [
-                {
-                  "color": "$deck-fill",
-                  "position": 0
-                },
-                {
-                  "color": "$deck-fill-deep",
-                  "position": 1
-                }
-              ]
-            },
-            "#FFFFFF12"
-          ],
-          "cornerRadius": 26,
-          "effect": {
-            "type": "shadow",
-            "shadowType": "outer",
-            "color": "#0B16231F",
-            "offset": {
-              "x": 0,
-              "y": 14
-            },
-            "blur": 28
-          },
-          "layout": "vertical",
-          "gap": 14,
-          "padding": 22,
-          "children": [
-            {
-              "type": "text",
-              "id": "healthyEyebrow",
-              "name": "heroEyebrow",
-              "content": "Diagnostics",
-              "fill": "$accent-amber",
-              "fontFamily": "Inter",
-              "fontSize": 12,
-              "fontWeight": "700",
-              "letterSpacing": 1.4
-            },
-            {
-              "type": "text",
-              "id": "healthyTitle",
-              "name": "heroTitle",
-              "content": "Healthy runway",
-              "fill": "#FFFDF8",
-              "fontFamily": "Inter",
-              "fontSize": 28,
-              "fontWeight": "700",
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            }
-          ]
-        },
-        {
-          "type": "frame",
-          "id": "panelHealthy",
-          "name": "Runway Panel",
-          "width": "fill_container",
-          "fill": "$surface-panel",
-          "cornerRadius": 24,
-          "stroke": {
-            "fill": "$surface-border",
-            "thickness": 1
-          },
-          "layout": "vertical",
-          "gap": 12,
-          "padding": 18,
-          "children": [
-            {
-              "type": "text",
-              "id": "panelHealthyTitle",
-              "name": "panelTitle",
-              "content": "Launch blocking scenarios",
-              "fill": "$surface-ink",
-              "fontFamily": "Inter",
-              "fontSize": 24,
-              "fontWeight": "700",
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            },
-            {
-              "type": "text",
-              "id": "panelHealthyBody",
-              "name": "panelBody",
-              "content": "Routine and high-risk controls are separated so the dangerous path always reads clearly.",
-              "fill": "$surface-muted",
-              "fontFamily": "Inter",
-              "fontSize": 14,
-              "fontWeight": "normal",
-              "lineHeight": 1.45,
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "frame",
-      "id": "degraded",
-      "x": 500,
-      "y": 0,
-      "name": "Diagnostics Console / Degraded",
-      "width": 420,
-      "fill": "$surface-bg",
-      "layout": "vertical",
-      "gap": 18,
-      "padding": [
-        18,
-        18,
-        24,
-        18
-      ],
-      "children": [
-        {
-          "type": "frame",
-          "id": "deckDegraded",
-          "name": "Command Deck",
-          "width": "fill_container",
-          "fill": [
-            {
-              "type": "gradient",
-              "gradientType": "linear",
-              "enabled": true,
-              "rotation": 180,
-              "size": {
-                "height": 1
-              },
-              "colors": [
-                {
-                  "color": "$deck-fill",
-                  "position": 0
-                },
-                {
-                  "color": "$deck-fill-deep",
-                  "position": 1
-                }
-              ]
-            },
-            "#FFFFFF12"
-          ],
-          "cornerRadius": 26,
-          "effect": {
-            "type": "shadow",
-            "shadowType": "outer",
-            "color": "#0B16231F",
-            "offset": {
-              "x": 0,
-              "y": 14
-            },
-            "blur": 28
-          },
-          "layout": "vertical",
-          "gap": 14,
-          "padding": 22,
-          "children": [
-            {
-              "type": "text",
-              "id": "degradedEyebrow",
-              "name": "heroEyebrow",
-              "content": "Diagnostics",
-              "fill": "$accent-amber",
-              "fontFamily": "Inter",
-              "fontSize": 12,
-              "fontWeight": "700",
-              "letterSpacing": 1.4
-            },
-            {
-              "type": "text",
-              "id": "degradedTitle",
-              "name": "heroTitle",
-              "content": "Degraded runway",
-              "fill": "#FFFDF8",
-              "fontFamily": "Inter",
-              "fontSize": 28,
-              "fontWeight": "700",
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            }
-          ]
-        },
-        {
-          "type": "frame",
-          "id": "panelDegraded",
-          "name": "Runway Panel",
-          "width": "fill_container",
-          "fill": "$surface-panel",
-          "cornerRadius": 24,
-          "stroke": {
-            "fill": "$surface-border",
-            "thickness": 1
-          },
-          "layout": "vertical",
-          "gap": 12,
-          "padding": 18,
-          "children": [
-            {
-              "type": "text",
-              "id": "panelDegradedTitle",
-              "name": "panelTitle",
-              "content": "Signal drift detected",
-              "fill": "$surface-ink",
-              "fontFamily": "Inter",
-              "fontSize": 24,
-              "fontWeight": "700",
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            },
-            {
-              "type": "text",
-              "id": "panelDegradedBody",
-              "name": "panelBody",
-              "content": "Telemetry stays legible while the top surface shifts the operator toward the corrective lane.",
-              "fill": "$surface-muted",
-              "fontFamily": "Inter",
-              "fontSize": 14,
-              "fontWeight": "normal",
-              "lineHeight": 1.45,
-              "textGrowth": "fixed-width",
-              "width": "fill_container"
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}