@xenonbyte/da-vinci-workflow 0.1.21 → 0.1.23

package/references/artifact-templates.md

@@ -166,6 +166,17 @@ Use this structure:
 - Require Adapter
 - Require Supervisor Review
 
+## Icon System Guidance (Advisory)
+- Goal
+- Source
+- Allowed families
+- Default family
+- Default spec
+- Reuse rule
+- Placeholder policy
+- Review requirement
+- Checkpoint policy (`WARN` by default)
+
 ## Do
 - approved stylistic moves
 
@@ -189,6 +200,19 @@ Field meaning:
 - `Fallback`: what to do when preferred adapters are unavailable
 - `Require Adapter`: whether missing adapters should block the workflow
 - `Require Supervisor Review`: whether missing, blocked, or unaccepted `design-supervisor review` should block broad expansion, implementation-task handoff, or terminal completion
+- `Icon System Guidance (Advisory)`: optional project-level icon consistency guidance; keep this non-blocking by default and escalate to hard gate only when explicit signoff is required
+
+Icon System Guidance field meaning:
+
+- `Goal`: icon-quality objective for this project (consistency, readability, brand fit)
+- `Source`: expected icon source policy, typically preferring `icon_font` for functional icons
+- `Allowed families`: approved icon families for this project
+- `Default family`: preferred baseline family to reduce mixed-style drift
+- `Default spec`: baseline size/weight/color-token rules for functional icons
+- `Reuse rule`: whether icon variants should be consolidated as reusable components before broad expansion
+- `Placeholder policy`: what counts as unacceptable placeholder icon usage
+- `Review requirement`: icon checks reviewers must explicitly record per anchor review
+- `Checkpoint policy`: whether unresolved icon issues default to `WARN` or `BLOCK`
 
 Use this artifact as a project-level visual contract. Generate it when the project does not already have one.
 

package/references/icon-aliases.example.json

@@ -0,0 +1,12 @@
+{
+  "aliases": {
+    "保险箱": ["vault", "safe box", "archive", "inventory_2"],
+    "解密": ["unlock", "lock_open", "key", "verified_user"],
+    "重试": ["refresh", "retry", "sync", "rotate-cw", "arrow-clockwise"],
+    "客服": ["headset", "support_agent", "message-circle", "chat"],
+    "工单": ["ticket", "file-text", "message-square"],
+    "风控": ["shield", "shield-check", "verified_user"],
+    "登录": ["login", "log-in", "sign-in", "person"],
+    "退出": ["logout", "log-out", "sign-out"]
+  }
+}

package/scripts/fixtures/mock-pencil.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+
+function getArg(flag) {
+  const index = process.argv.indexOf(flag);
+  if (index < 0) {
+    return undefined;
+  }
+  return process.argv[index + 1];
+}
+
+function safeReadJson(filePath, fallback) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    return fallback;
+  }
+}
+
+function main() {
+  const inputPath = getArg("-i");
+  const outputPath = getArg("-o");
+  const commandText = fs.readFileSync(0, "utf8");
+  const document = safeReadJson(inputPath, { children: [], variables: {} });
+
+  let payload;
+  if (/get_variables\s*\(/.test(commandText)) {
+    payload = {
+      variables: document && typeof document.variables === "object" ? document.variables : {}
+    };
+  } else {
+    payload = {
+      nodes: Array.isArray(document.children) ? document.children : []
+    };
+  }
+
+  if (outputPath) {
+    const data = inputPath && fs.existsSync(inputPath) ? fs.readFileSync(inputPath, "utf8") : '{"version":"2.9","children":[]}\n';
+    fs.writeFileSync(outputPath, data);
+  }
+
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+main();

package/scripts/test-audit-safety.js

@@ -0,0 +1,92 @@
+const assert = require("assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const { auditProject } = require("../lib/audit");
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+function writeText(filePath, text) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, text);
+}
+
+function setupProject(name) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), `da-vinci-audit-safety-${name}-`));
+  const daVinciDir = path.join(root, ".da-vinci");
+  const designsDir = path.join(daVinciDir, "designs");
+  const designRegistryPath = path.join(daVinciDir, "design-registry.md");
+
+  writeText(path.join(root, "DA-VINCI.md"), "# DA-VINCI\n");
+  writeText(path.join(daVinciDir, "project-inventory.md"), "# Inventory\n");
+  writeText(path.join(daVinciDir, "page-map.md"), "# Page Map\n");
+  fs.mkdirSync(designsDir, { recursive: true });
+
+  return {
+    root,
+    daVinciDir,
+    designsDir,
+    designRegistryPath
+  };
+}
+
+runTest("integrity audit warns when registry contains out-of-root .pen reference", () => {
+  const project = setupProject("escaped-registry");
+  writeText(path.join(project.designsDir, "main.pen"), "{}");
+  writeText(
+    project.designRegistryPath,
+    [
+      "# Registry",
+      "- Preferred .pen: .da-vinci/designs/main.pen",
+      "- Legacy .pen: .da-vinci/designs/../../../outside.pen",
+      ""
+    ].join("\n")
+  );
+
+  const result = auditProject(project.root, {
+    mode: "integrity"
+  });
+
+  assert.equal(result.failures.length, 0);
+  assert.match(result.warnings.join("\n"), /escapes project root and will be ignored/i);
+});
+
+runTest("integrity audit surfaces traversal truncation warnings on deep trees", () => {
+  const project = setupProject("truncated-scan");
+  writeText(path.join(project.designsDir, "main.pen"), "{}");
+  writeText(
+    project.designRegistryPath,
+    [
+      "# Registry",
+      "- Preferred .pen: .da-vinci/designs/main.pen",
+      ""
+    ].join("\n")
+  );
+
+  let current = project.designsDir;
+  for (let depth = 0; depth < 30; depth += 1) {
+    current = path.join(current, `deep-${depth}`);
+    fs.mkdirSync(current, { recursive: true });
+  }
+  writeText(path.join(current, "deep-tree.pen"), "{}");
+
+  const result = auditProject(project.root, {
+    mode: "integrity"
+  });
+
+  assert.match(
+    result.warnings.join("\n"),
+    /File scan truncated under \.da-vinci[\/\\]designs/i
+  );
+});
+
+console.log("All audit safety tests passed.");

package/scripts/test-icon-aliases.js

@@ -0,0 +1,96 @@
+const assert = require("assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  DEFAULT_ALIASES,
+  getDefaultAliasPath,
+  resolveAliasPath,
+  loadIconAliases,
+  expandQueryWithAliases,
+  normalizeAliasMap
+} = require("../lib/icon-aliases");
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+runTest("default aliases include vault semantics", () => {
+  assert.ok(Array.isArray(DEFAULT_ALIASES["保险箱"]));
+  assert.ok(DEFAULT_ALIASES["保险箱"].includes("vault"));
+});
+
+runTest("normalizeAliasMap normalizes keys and values", () => {
+  const map = normalizeAliasMap({
+    "  设 置 ": [" settings ", "tune"],
+    "": ["ignored"]
+  });
+  assert.ok(map["设 置"]);
+  assert.deepEqual(map["设 置"], ["settings", "tune"]);
+});
+
+runTest("default alias path resolves under home", () => {
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-alias-home-"));
+  const aliasPath = getDefaultAliasPath(tempHome);
+  assert.match(aliasPath, /\.da-vinci[\/\\]icon-aliases\.json$/);
+});
+
+runTest("loadIconAliases merges user file over defaults", () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-alias-file-"));
+  const aliasPath = path.join(tempDir, "icon-aliases.json");
+  fs.writeFileSync(
+    aliasPath,
+    JSON.stringify(
+      {
+        aliases: {
+          "保险箱": ["vault", "safe-box-custom"],
+          "工单": ["ticket", "message-square"]
+        }
+      },
+      null,
+      2
+    )
+  );
+
+  const loaded = loadIconAliases({
+    aliasPath
+  });
+  assert.equal(loaded.loaded, true);
+  assert.equal(loaded.source, "file");
+  assert.ok(loaded.aliases["保险箱"].includes("safe-box-custom"));
+  assert.ok(loaded.aliases["工单"].includes("ticket"));
+});
+
+runTest("expandQueryWithAliases adds mapped extra tokens", () => {
+  const expansion = expandQueryWithAliases("保险箱 解密", {
+    ...normalizeAliasMap(DEFAULT_ALIASES),
+    工单: ["ticket"]
+  });
+  assert.ok(expansion.extraTokens.includes("vault"));
+  assert.ok(expansion.extraTokens.includes("unlock"));
+  assert.ok(expansion.matchedAliases.length >= 2);
+});
+
+runTest("alias expansion normalizes diacritics in user query", () => {
+  const expansion = expandQueryWithAliases("SéTTings", normalizeAliasMap({
+    ...DEFAULT_ALIASES,
+    settings: ["settings", "tune"]
+  }));
+  assert.ok(expansion.extraTokens.includes("settings"));
+  assert.ok(expansion.extraTokens.includes("tune"));
+});
+
+runTest("resolveAliasPath returns absolute path", () => {
+  const resolved = resolveAliasPath({
+    aliasPath: "./tmp/icon-aliases.json"
+  });
+  assert.ok(path.isAbsolute(resolved));
+});
+
+console.log("All icon-aliases tests passed.");

package/scripts/test-icon-search.js

@@ -0,0 +1,77 @@
+const assert = require("assert/strict");
+const {
+  searchIconLibrary,
+  formatIconSearchReport
+} = require("../lib/icon-search");
+
+function runTest(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+runTest("exact settings query ranks material rounded first", () => {
+  const result = searchIconLibrary("settings", { top: 5 });
+  assert.ok(result.matches.length > 0);
+  assert.equal(result.matches[0].family, "Material Symbols Rounded");
+  assert.equal(result.matches[0].name, "settings");
+});
+
+runTest("chinese query can resolve settings candidates", () => {
+  const result = searchIconLibrary("设置", { top: 5 });
+  assert.ok(result.matches.some((match) => match.name === "settings"));
+});
+
+runTest("accented latin query is normalized consistently", () => {
+  const result = searchIconLibrary("séttings", { top: 5 });
+  assert.ok(result.matches.some((match) => match.name === "settings"));
+});
+
+runTest("family filter returns only the selected family", () => {
+  const result = searchIconLibrary("lock", { family: "lucide", top: 6 });
+  assert.ok(result.matches.length > 0);
+  for (const match of result.matches) {
+    assert.equal(match.family, "lucide");
+  }
+});
+
+runTest("material family alias expands to all material variants", () => {
+  const result = searchIconLibrary("home", { family: "material", top: 6 });
+  const families = new Set(result.matches.map((match) => match.family));
+  assert.ok(families.has("Material Symbols Rounded"));
+  assert.ok(families.has("Material Symbols Outlined"));
+  assert.ok(families.has("Material Symbols Sharp"));
+});
+
+runTest("unknown family filter throws a clear error", () => {
+  assert.throws(() => searchIconLibrary("lock", { family: "unknown-family" }), /Unknown icon family filter/i);
+});
+
+runTest("formatted report contains node payload hints", () => {
+  const result = searchIconLibrary("vault", { top: 3 });
+  const report = formatIconSearchReport(result);
+  assert.match(report, /Icon Search/);
+  assert.match(report, /node:/);
+  assert.match(report, /iconFontFamily/);
+});
+
+runTest("external catalog records are merged into search candidates", () => {
+  const result = searchIconLibrary("launch rocket", {
+    top: 5,
+    catalog: [
+      {
+        family: "lucide",
+        name: "rocket",
+        semantic: "rocket",
+        tags: ["launch"]
+      }
+    ]
+  });
+  assert.ok(result.matches.some((match) => match.family === "lucide" && match.name === "rocket"));
+});
+
+console.log("All icon-search tests passed.");

package/scripts/test-icon-sync.js

@@ -0,0 +1,178 @@
+const assert = require("assert/strict");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  MATERIAL_METADATA_URL,
+  LUCIDE_TREE_URL,
+  FEATHER_TREE_URL,
+  PHOSPHOR_TREE_URL,
+  getDefaultCatalogPath,
+  resolveCatalogPath,
+  loadIconCatalog,
+  syncIconCatalog,
+  formatIconSyncReport,
+  parseGoogleMaterialMetadata,
+  parseGitHubTreeIcons,
+  dedupeIconRecords,
+  summarizeSourceResults
+} = require("../lib/icon-sync");
+
+async function runTest(name, fn) {
+  try {
+    await fn();
+    console.log(`PASS ${name}`);
+  } catch (error) {
+    console.error(`FAIL ${name}`);
+    throw error;
+  }
+}
+
+function createMockFetch({ failLucide = false } = {}) {
+  return async (url) => {
+    if (url === MATERIAL_METADATA_URL) {
+      return `)]}'\n{"icons":[{"name":"settings","unsupported_families":[]}]}`;
+    }
+    if (url === LUCIDE_TREE_URL) {
+      if (failLucide) {
+        throw new Error("mock lucide outage");
+      }
+      return JSON.stringify({
+        tree: [{ path: "icons/settings.json" }]
+      });
+    }
+    if (url === FEATHER_TREE_URL) {
+      return JSON.stringify({
+        tree: [{ path: "icons/lock.svg" }]
+      });
+    }
+    if (url === PHOSPHOR_TREE_URL) {
+      return JSON.stringify({
+        tree: [{ path: "assets/regular/vault.svg" }]
+      });
+    }
+    throw new Error(`Unexpected URL: ${url}`);
+  };
+}
+
+(async () => {
+  await runTest("google metadata parser extracts material variants", () => {
+    const raw = `)]}'\n{"icons":[{"name":"settings","unsupported_families":[]},{"name":"lock_open","unsupported_families":["Material Icons Sharp"]}]}`;
+    const records = parseGoogleMaterialMetadata(raw);
+    const keys = new Set(records.map((record) => `${record.family}/${record.name}`));
+    assert.ok(keys.has("Material Symbols Rounded/settings"));
+    assert.ok(keys.has("Material Symbols Outlined/settings"));
+    assert.ok(keys.has("Material Symbols Sharp/settings"));
+    assert.ok(keys.has("Material Symbols Rounded/lock_open"));
+    assert.equal(keys.has("Material Symbols Sharp/lock_open"), false);
+  });
+
+  await runTest("github tree parser extracts icon names from paths", () => {
+    const raw = JSON.stringify({
+      tree: [
+        { path: "icons/settings.json" },
+        { path: "icons/lock-open.json" },
+        { path: "icons/nested/skip.json" },
+        { path: "readme.md" }
+      ]
+    });
+    const records = parseGitHubTreeIcons(raw, {
+      family: "lucide",
+      prefix: "icons/",
+      suffix: ".json"
+    });
+    const names = records.map((record) => record.name);
+    assert.deepEqual(names, ["settings", "lock-open"]);
+  });
+
+  await runTest("dedupe keeps first unique family/name pair", () => {
+    const deduped = dedupeIconRecords([
+      { family: "lucide", name: "settings" },
+      { family: "lucide", name: "settings" },
+      { family: "feather", name: "settings" }
+    ]);
+    assert.equal(deduped.length, 2);
+  });
+
+  await runTest("catalog path resolves to home .da-vinci directory by default", () => {
+    const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-icon-home-"));
+    const resolved = getDefaultCatalogPath(tempHome);
+    assert.match(resolved, /\.da-vinci[\/\\]icon-catalog\.json$/);
+  });
+
+  await runTest("load icon catalog reads valid schema", () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-icon-catalog-"));
+    const catalogPath = path.join(tempDir, "icon-catalog.json");
+    fs.writeFileSync(
+      catalogPath,
+      JSON.stringify(
+        {
+          schema: 1,
+          generatedAt: "2026-03-29T00:00:00.000Z",
+          iconCount: 1,
+          icons: [{ family: "lucide", name: "settings", semantic: "settings", tags: [] }]
+        },
+        null,
+        2
+      )
+    );
+
+    const loaded = loadIconCatalog({
+      catalogPath
+    });
+    assert.ok(loaded.catalog);
+    assert.equal(loaded.catalog.icons.length, 1);
+    assert.equal(resolveCatalogPath({ catalogPath }), path.resolve(catalogPath));
+  });
+
+  await runTest("source summary marks degraded when at least one source errors", () => {
+    const summary = summarizeSourceResults({
+      material: { status: "ok" },
+      lucide: { status: "error" },
+      feather: { status: "ok" }
+    });
+    assert.deepEqual(summary, {
+      total: 3,
+      okCount: 2,
+      errorCount: 1,
+      degraded: true
+    });
+  });
+
+  await runTest("icon sync keeps flow non-blocking by default on partial source failure", async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-icon-sync-"));
+    const outputPath = path.join(tempDir, "catalog.json");
+    const result = await syncIconCatalog({
+      outputPath,
+      fetchText: createMockFetch({ failLucide: true })
+    });
+
+    assert.equal(result.catalog.syncStatus, "degraded");
+    assert.equal(result.catalog.sourceResults.lucide.status, "error");
+    assert.ok(result.catalog.iconCount > 0);
+    assert.equal(fs.existsSync(outputPath), true);
+    assert.match(formatIconSyncReport(result), /Status: DEGRADED/i);
+  });
+
+  await runTest("icon sync strict mode fails on partial source failure and does not write partial catalog", async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-icon-sync-strict-"));
+    const outputPath = path.join(tempDir, "catalog.json");
+
+    await assert.rejects(
+      () =>
+        syncIconCatalog({
+          outputPath,
+          strict: true,
+          fetchText: createMockFetch({ failLucide: true })
+        }),
+      /strict mode failed/i
+    );
+
+    assert.equal(fs.existsSync(outputPath), false);
+  });
+
+  console.log("All icon-sync tests passed.");
+})().catch((error) => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/scripts/test-pen-persistence.js

@@ -17,6 +17,7 @@ const {
 } = require("../lib/pencil-lock");
 
 const fixturePath = path.join(__dirname, "fixtures", "complex-sample.pen");
+const mockPencilPath = path.join(__dirname, "fixtures", "mock-pencil.js");
 
 function runTest(name, fn) {
   try {
@@ -65,7 +66,8 @@ runTest("writePenFromPayloadFiles writes and reopens a complex sample", () => {
     nodesFile,
     variablesFile,
     version: fixture.version,
-    verifyWithPencil: true
+    verifyWithPencil: true,
+    pencilBin: mockPencilPath
   });
 
   const written = JSON.parse(fs.readFileSync(outputPath, "utf8"));
@@ -82,7 +84,8 @@ runTest("snapshotPenFile round-trips a complex sample", () => {
   const result = snapshotPenFile({
     inputPath: fixturePath,
     outputPath,
-    verifyWithPencil: true
+    verifyWithPencil: true,
+    pencilBin: mockPencilPath
   });
 
   const written = JSON.parse(fs.readFileSync(outputPath, "utf8"));
@@ -97,7 +100,8 @@ runTest("ensurePenFile seeds a missing project-local .pen and state", () => {
 
   const result = ensurePenFile({
     outputPath,
-    verifyWithPencil: true
+    verifyWithPencil: true,
+    pencilBin: mockPencilPath
   });
 
   const written = JSON.parse(fs.readFileSync(outputPath, "utf8"));

package/scripts/test-pencil-preflight.js

@@ -125,6 +125,22 @@ runTest("invalid gradient size fails preflight", () => {
   assert.match(result.failures.join("\n"), /size\/height must be a number or "\$variable"/i);
 });
 
+runTest("unsafe runtime globals are rejected before sandbox execution", () => {
+  const result = preflightPencilBatch(
+    'frame=I(document,{type:"frame",width:10,height:10,fill:"#FFFFFF"})\nprocess.env.SECRET'
+  );
+
+  assert.equal(result.status, FAIL);
+  assert.match(result.failures.join("\n"), /runtime globals or prototype internals/i);
+});
+
+runTest("sandbox timeout failures are classified explicitly", () => {
+  const result = preflightPencilBatch("while(true){}");
+
+  assert.equal(result.status, FAIL);
+  assert.match(result.failures.join("\n"), /execution timed out in preflight sandbox/i);
+});
+
 runTest("large anchor-sized batch warns", () => {
   const lines = [];
   for (let index = 0; index < 13; index += 1) {