@xenonbyte/da-vinci-workflow 0.1.21 → 0.1.22

package/lib/icon-sync.js

@@ -0,0 +1,361 @@
+const fs = require("fs");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const {
+  MATERIAL_ROUNDED,
+  MATERIAL_OUTLINED,
+  MATERIAL_SHARP
+} = require("./icon-search");
+
+const MATERIAL_METADATA_URL = "https://fonts.google.com/metadata/icons";
+const LUCIDE_TREE_URL = "https://api.github.com/repos/lucide-icons/lucide/git/trees/main?recursive=1";
+const FEATHER_TREE_URL = "https://api.github.com/repos/feathericons/feather/git/trees/main?recursive=1";
+const PHOSPHOR_TREE_URL = "https://api.github.com/repos/phosphor-icons/core/git/trees/main?recursive=1";
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function toBoolean(value) {
+  if (value === true || value === false) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) {
+      return true;
+    }
+    if (["0", "false", "no", "off"].includes(normalized)) {
+      return false;
+    }
+  }
+  return Boolean(value);
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function normalizeName(name) {
+  return String(name || "").trim();
+}
+
+function makeIconRecord(family, name) {
+  const normalized = normalizeName(name);
+  if (!family || !normalized) {
+    return null;
+  }
+  return {
+    family,
+    name: normalized,
+    semantic: normalized.replace(/[_-]+/g, " "),
+    tags: []
+  };
+}
+
+function parseGoogleMaterialMetadata(raw) {
+  const text = String(raw || "");
+  const objectStart = text.indexOf("{");
+  if (objectStart < 0) {
+    throw new Error("Material metadata payload is not valid JSON.");
+  }
+  const parsed = JSON.parse(text.slice(objectStart));
+  const icons = Array.isArray(parsed.icons) ? parsed.icons : [];
+  const roundedFamilyKey = "Material Icons Round";
+  const outlinedFamilyKey = "Material Icons Outlined";
+  const sharpFamilyKey = "Material Icons Sharp";
+
+  return icons.flatMap((item) => {
+    const name = normalizeName(item && item.name);
+    if (!name) {
+      return [];
+    }
+    const unsupported = new Set(Array.isArray(item.unsupported_families) ? item.unsupported_families : []);
+    const records = [];
+
+    if (!unsupported.has(roundedFamilyKey)) {
+      records.push(makeIconRecord(MATERIAL_ROUNDED, name));
+    }
+    if (!unsupported.has(outlinedFamilyKey)) {
+      records.push(makeIconRecord(MATERIAL_OUTLINED, name));
+    }
+    if (!unsupported.has(sharpFamilyKey)) {
+      records.push(makeIconRecord(MATERIAL_SHARP, name));
+    }
+
+    return records.filter(Boolean);
+  });
+}
+
+function parseGitHubTreeIcons(raw, options) {
+  const { family, prefix, suffix } = options;
+  const parsed = JSON.parse(String(raw || ""));
+  const tree = Array.isArray(parsed.tree) ? parsed.tree : [];
+
+  return tree
+    .flatMap((node) => {
+      const nodePath = normalizeName(node && node.path);
+      if (!nodePath || !nodePath.startsWith(prefix) || !nodePath.endsWith(suffix)) {
+        return [];
+      }
+      const name = nodePath.slice(prefix.length, nodePath.length - suffix.length);
+      if (!name || name.includes("/")) {
+        return [];
+      }
+      const record = makeIconRecord(family, name);
+      return record ? [record] : [];
+    });
+}
+
+function dedupeIconRecords(records) {
+  const map = new Map();
+  for (const record of records) {
+    if (!record) {
+      continue;
+    }
+    const key = `${record.family}::${record.name}`;
+    if (!map.has(key)) {
+      map.set(key, record);
+    }
+  }
+  return Array.from(map.values());
+}
+
+function summarizeSourceResults(sourceResults = {}) {
+  const entries = Object.values(sourceResults);
+  const total = entries.length;
+  const errorCount = entries.filter((source) => source && source.status === "error").length;
+  const okCount = entries.filter((source) => source && source.status === "ok").length;
+  return {
+    total,
+    okCount,
+    errorCount,
+    degraded: errorCount > 0
+  };
+}
+
+function fetchText(url, options = {}) {
+  const timeoutMs = Number.isFinite(Number(options.timeoutMs))
+    ? Number(options.timeoutMs)
+    : DEFAULT_TIMEOUT_MS;
+
+  return new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      {
+        headers: {
+          "User-Agent": "da-vinci-workflow/icon-sync",
+          Accept: "application/json,text/plain,*/*"
+        }
+      },
+      (response) => {
+        let data = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          data += chunk;
+        });
+        response.on("end", () => {
+          if (response.statusCode && response.statusCode >= 400) {
+            reject(new Error(`HTTP ${response.statusCode} for ${url}`));
+            return;
+          }
+          resolve(data);
+        });
+      }
+    );
+
+    request.on("error", (error) => {
+      reject(error);
+    });
+
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`Request timeout after ${timeoutMs}ms for ${url}`));
+    });
+  });
+}
+
+function getDefaultCatalogPath(homeDir) {
+  const root = homeDir ? path.resolve(homeDir) : os.homedir();
+  return path.join(root, ".da-vinci", "icon-catalog.json");
+}
+
+function resolveCatalogPath(options = {}) {
+  if (options.catalogPath) {
+    return path.resolve(options.catalogPath);
+  }
+  if (options.outputPath) {
+    return path.resolve(options.outputPath);
+  }
+  return path.resolve(getDefaultCatalogPath(options.homeDir));
+}
+
+function loadIconCatalog(options = {}) {
+  const catalogPath = resolveCatalogPath(options);
+  if (!fs.existsSync(catalogPath)) {
+    return {
+      catalogPath,
+      catalog: null
+    };
+  }
+
+  const parsed = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+  if (!parsed || !Array.isArray(parsed.icons)) {
+    throw new Error(`Invalid icon catalog format: ${catalogPath}`);
+  }
+
+  return {
+    catalogPath,
+    catalog: parsed
+  };
+}
+
+async function syncIconCatalog(options = {}) {
+  const catalogPath = resolveCatalogPath(options);
+  const timeoutMs = Number.isFinite(Number(options.timeoutMs))
+    ? Number(options.timeoutMs)
+    : DEFAULT_TIMEOUT_MS;
+  const strict = toBoolean(options.strict);
+  const fetchTextImpl = typeof options.fetchText === "function" ? options.fetchText : fetchText;
+
+  const sourceSpecs = [
+    {
+      key: "material",
+      url: MATERIAL_METADATA_URL,
+      parse: parseGoogleMaterialMetadata
+    },
+    {
+      key: "lucide",
+      url: LUCIDE_TREE_URL,
+      parse: (raw) =>
+        parseGitHubTreeIcons(raw, {
+          family: "lucide",
+          prefix: "icons/",
+          suffix: ".json"
+        })
+    },
+    {
+      key: "feather",
+      url: FEATHER_TREE_URL,
+      parse: (raw) =>
+        parseGitHubTreeIcons(raw, {
+          family: "feather",
+          prefix: "icons/",
+          suffix: ".svg"
+        })
+    },
+    {
+      key: "phosphor",
+      url: PHOSPHOR_TREE_URL,
+      parse: (raw) =>
+        parseGitHubTreeIcons(raw, {
+          family: "phosphor",
+          prefix: "assets/regular/",
+          suffix: ".svg"
+        })
+    }
+  ];
+
+  const sourceResults = {};
+  const collected = [];
+
+  await Promise.all(
+    sourceSpecs.map(async (spec) => {
+      try {
+        const raw = await fetchTextImpl(spec.url, {
+          timeoutMs
+        });
+        const records = spec.parse(raw);
+        sourceResults[spec.key] = {
+          status: "ok",
+          url: spec.url,
+          count: records.length
+        };
+        collected.push(...records);
+      } catch (error) {
+        sourceResults[spec.key] = {
+          status: "error",
+          url: spec.url,
+          count: 0,
+          error: error.message || String(error)
+        };
+      }
+    })
+  );
+
+  const icons = dedupeIconRecords(collected);
+  const sourceSummary = summarizeSourceResults(sourceResults);
+  if (icons.length === 0) {
+    throw new Error(
+      [
+        "icon-sync failed: no icon records were fetched.",
+        ...Object.entries(sourceResults).map(([key, value]) => `${key}: ${value.status}${value.error ? ` (${value.error})` : ""}`)
+      ].join("\n")
+    );
+  }
+  if (strict && sourceSummary.errorCount > 0) {
+    throw new Error(
+      [
+        "icon-sync strict mode failed: one or more upstream sources could not be fetched.",
+        ...Object.entries(sourceResults).map(([key, value]) => `${key}: ${value.status}${value.error ? ` (${value.error})` : ""}`)
+      ].join("\n")
+    );
+  }
+
+  const catalog = {
+    schema: 1,
+    generatedAt: new Date().toISOString(),
+    sourceResults,
+    sourceSummary,
+    syncStatus: sourceSummary.degraded ? "degraded" : "ok",
+    iconCount: icons.length,
+    icons
+  };
+
+  ensureDir(catalogPath);
+  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2));
+
+  return {
+    catalogPath,
+    catalog
+  };
+}
+
+function formatIconSyncReport(result) {
+  const sourceSummary = result.catalog.sourceSummary || summarizeSourceResults(result.catalog.sourceResults || {});
+  const statusLine = sourceSummary.degraded
+    ? `DEGRADED (${sourceSummary.errorCount}/${sourceSummary.total} source failures)`
+    : "OK";
+  const lines = [
+    "Icon Sync",
+    `Catalog path: ${result.catalogPath}`,
+    `Generated at: ${result.catalog.generatedAt}`,
+    `Status: ${statusLine}`,
+    `Icon count: ${result.catalog.iconCount}`,
+    "Sources:"
+  ];
+
+  for (const [key, source] of Object.entries(result.catalog.sourceResults || {})) {
+    const base = `- ${key}: ${source.status} (${source.count})`;
+    if (source.error) {
+      lines.push(`${base} ${source.error}`);
+      continue;
+    }
+    lines.push(base);
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  MATERIAL_METADATA_URL,
+  LUCIDE_TREE_URL,
+  FEATHER_TREE_URL,
+  PHOSPHOR_TREE_URL,
+  getDefaultCatalogPath,
+  resolveCatalogPath,
+  loadIconCatalog,
+  syncIconCatalog,
+  formatIconSyncReport,
+  parseGoogleMaterialMetadata,
+  parseGitHubTreeIcons,
+  dedupeIconRecords,
+  summarizeSourceResults
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"
@@ -30,7 +30,10 @@
     "test:persistence-flows": "node scripts/test-persistence-flows.js",
     "test:pencil-session": "node scripts/test-pencil-session.js",
     "test:pencil-preflight": "node scripts/test-pencil-preflight.js",
-    "test:pen-persistence": "node scripts/test-pen-persistence.js"
+    "test:pen-persistence": "node scripts/test-pen-persistence.js",
+    "test:icon-search": "node scripts/test-icon-search.js",
+    "test:icon-sync": "node scripts/test-icon-sync.js",
+    "test:icon-aliases": "node scripts/test-icon-aliases.js"
   },
   "engines": {
     "node": ">=18"

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-icon-aliases.js

@@ -0,0 +1,87 @@
+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("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,72 @@
+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("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.");