@xenonbyte/da-vinci-workflow 0.1.20 → 0.1.22

package/examples/greenfield-spec-markupflow/README.md

@@ -46,6 +46,13 @@ Visual adapter used for this forward test:
 - runtime declaration: explicit before first anchor pass
 - fallback: `native-da-vinci` if no local adapter were available
 
+Icon library workflow used for this forward test:
+
+- sync command: `da-vinci icon-sync`
+- alias template: `cp references/icon-aliases.example.json ~/.da-vinci/icon-aliases.json`
+- lookup command example: `da-vinci icon-search --query "settings publish workflow" --family material --top 6`
+- gate policy: icon lookup remains advisory by default; use `--strict` only for explicit CI hard gates
+
 Important note:
 
 - the `.pen` source was authored in a live Pencil session and the example records `.da-vinci/designs/project-baseline.pen` as the intended project-local persisted path

package/examples/greenfield-spec-markupflow/pencil-design.md

@@ -41,6 +41,11 @@
 - keep the structural emphasis on three core capabilities on page one
 - keep the import, annotate, publish pipeline readable on page two
 
+## Icon Notes
+- functional icons are expected to use `icon_font` instead of placeholder geometry
+- preferred family for this pass: `Material Symbols Rounded`
+- when icon intent is ambiguous, resolve candidates via `da-vinci icon-search` before writing `batch_design`
+
 ## Validation Notes
 - both screens were reviewed in Pencil during authoring
 - no obvious clipping, overlap, or alignment failures were observed in the design pass

package/lib/cli.js

@@ -29,6 +29,19 @@ const {
   endPencilSession,
   getPencilSessionStatus
 } = require("./pencil-session");
+const {
+  searchIconLibrary,
+  formatIconSearchReport
+} = require("./icon-search");
+const {
+  syncIconCatalog,
+  loadIconCatalog,
+  formatIconSyncReport
+} = require("./icon-sync");
+const {
+  loadIconAliases,
+  expandQueryWithAliases
+} = require("./icon-aliases");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -90,6 +103,8 @@ function printHelp() {
       "  da-vinci status",
       "  da-vinci validate-assets",
       "  da-vinci audit [project-path]",
+      "  da-vinci icon-sync [--output <path>] [--timeout-ms <value>] [--strict]",
+      "  da-vinci icon-search --query <text> [--family <value>] [--top <value>] [--catalog <path>] [--aliases <path>] [--json]",
       "  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>]",
@@ -100,7 +115,7 @@ function printHelp() {
       "  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 end --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci pencil-session status --project <path>",
       "  da-vinci --version",
       "",
@@ -108,6 +123,14 @@ function printHelp() {
       "  --platform <value>   codex, claude, gemini, or all",
       "  --home <path>        override HOME for installation targets",
       "  --project <path>     override project path for audit",
+      "  --catalog <path>     icon catalog path for icon-search/icon-sync (default: ~/.da-vinci/icon-catalog.json)",
+      "  --aliases <path>     icon alias mapping file for icon-search (default: ~/.da-vinci/icon-aliases.json)",
+      "  --query <text>       icon-search query text",
+      "  --family <value>     icon-search family filter: all, material, rounded, outlined, sharp, lucide, feather, phosphor",
+      "  --top <value>        icon-search result count (1-50, default 8)",
+      "  --timeout-ms <value> network timeout for icon-sync requests",
+      "  --strict             fail icon-sync when any upstream source request fails",
+      "  --json               print structured JSON for icon-search",
       "  --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",
@@ -128,7 +151,28 @@ function printHelp() {
 async function runCli(argv) {
   const [command] = argv;
   const homeDir = getOption(argv, "--home");
-  const positionalArgs = getPositionalArgs(argv.slice(1), ["--home", "--platform", "--project", "--mode", "--change"]);
+  const positionalArgs = getPositionalArgs(argv.slice(1), [
+    "--home",
+    "--platform",
+    "--project",
+    "--mode",
+    "--change",
+    "--query",
+    "--family",
+    "--top",
+    "--catalog",
+    "--aliases",
+    "--timeout-ms",
+    "--ops-file",
+    "--input",
+    "--output",
+    "--pen",
+    "--nodes-file",
+    "--variables-file",
+    "--version",
+    "--owner",
+    "--wait-ms"
+  ]);
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -184,6 +228,149 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "icon-sync") {
+    const outputPath = getOption(argv, "--output") || getOption(argv, "--catalog");
+    const timeoutMs = getOption(argv, "--timeout-ms");
+    const strict = argv.includes("--strict");
+
+    const result = await syncIconCatalog({
+      outputPath,
+      timeoutMs,
+      strict,
+      homeDir
+    });
+
+    console.log(formatIconSyncReport(result));
+    return;
+  }
+
+  if (command === "icon-search") {
+    const family = getOption(argv, "--family") || "all";
+    const topRaw = getOption(argv, "--top");
+    const queryOption = getOption(argv, "--query");
+    const catalogPath = getOption(argv, "--catalog");
+    const aliasesPath = getOption(argv, "--aliases");
+    const iconPositional = getPositionalArgs(argv.slice(1), [
+      "--home",
+      "--query",
+      "--family",
+      "--top",
+      "--catalog",
+      "--aliases"
+    ]);
+    const query = queryOption || iconPositional.join(" ").trim();
+
+    if (!query) {
+      throw new Error("`icon-search` requires `--query <text>` or positional query text.");
+    }
+
+    let top;
+    if (topRaw !== undefined) {
+      top = Number.parseInt(topRaw, 10);
+      if (!Number.isFinite(top) || top < 1 || top > 50) {
+        throw new Error("`icon-search --top` must be an integer between 1 and 50.");
+      }
+    }
+
+    let loadedCatalog = null;
+    let loadedCatalogPath = null;
+    let catalogLoadError = null;
+    let loadedAliases = null;
+    let loadedAliasesPath = null;
+    let aliasesLoadError = null;
+    let aliasExpansion = {
+      extraTokens: [],
+      matchedAliases: []
+    };
+
+    try {
+      const loaded = loadIconCatalog({
+        catalogPath,
+        homeDir
+      });
+      loadedCatalog = loaded.catalog;
+      loadedCatalogPath = loaded.catalogPath;
+    } catch (error) {
+      catalogLoadError = error.message || String(error);
+    }
+
+    try {
+      const loaded = loadIconAliases({
+        aliasPath: aliasesPath,
+        homeDir
+      });
+      loadedAliases = loaded;
+      loadedAliasesPath = loaded.aliasPath;
+      aliasExpansion = expandQueryWithAliases(query, loaded.aliases);
+    } catch (error) {
+      aliasesLoadError = error.message || String(error);
+    }
+
+    const result = searchIconLibrary(query, {
+      family,
+      top,
+      catalog: loadedCatalog ? loadedCatalog.icons : [],
+      extraQueryTokens: aliasExpansion.extraTokens
+    });
+    const jsonOutput = argv.includes("--json");
+
+    const resultWithMeta = {
+      ...result,
+      catalog: {
+        path: loadedCatalogPath || "(unresolved)",
+        loaded: Boolean(loadedCatalog),
+        iconCount: loadedCatalog ? loadedCatalog.iconCount : 0,
+        generatedAt: loadedCatalog ? loadedCatalog.generatedAt : null,
+        error: catalogLoadError
+      },
+      aliases: {
+        path: loadedAliasesPath || "(unresolved)",
+        loaded: loadedAliases ? Boolean(loadedAliases.loaded) : false,
+        available: Boolean(loadedAliases),
+        source: loadedAliases ? loadedAliases.source : null,
+        matched: aliasExpansion.matchedAliases.length,
+        extraTokens: aliasExpansion.extraTokens,
+        error: aliasesLoadError
+      }
+    };
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(resultWithMeta, null, 2));
+      return;
+    }
+
+    if (resultWithMeta.catalog.loaded) {
+      console.log(
+        `Icon catalog: ${resultWithMeta.catalog.path} (${resultWithMeta.catalog.iconCount} icons, ${resultWithMeta.catalog.generatedAt})`
+      );
+    } else if (resultWithMeta.catalog.error) {
+      console.log(
+        `Icon catalog: ${resultWithMeta.catalog.path} (load failed: ${resultWithMeta.catalog.error}; using built-in fallback index)`
+      );
+    } else {
+      console.log(
+        `Icon catalog: ${resultWithMeta.catalog.path} (not found; using built-in fallback index; run \`da-vinci icon-sync\`)`
+      );
+    }
+
+    if (resultWithMeta.aliases.available) {
+      console.log(
+        `Icon aliases: ${resultWithMeta.aliases.path} (${resultWithMeta.aliases.source}, matched ${resultWithMeta.aliases.matched})`
+      );
+    } else if (resultWithMeta.aliases.error) {
+      console.log(
+        `Icon aliases: ${resultWithMeta.aliases.path} (load failed: ${resultWithMeta.aliases.error})`
+      );
+    } else {
+      console.log(
+        `Icon aliases: ${resultWithMeta.aliases.path} (not found; using built-in defaults only)`
+      );
+    }
+
+    console.log(formatIconSearchReport(result));
+    return;
+  }
+
   if (command === "preflight-pencil") {
     const opsFile = getOption(argv, "--ops-file");
     let operations = "";
@@ -456,6 +643,11 @@ async function runCli(argv) {
       if (!penPath) {
         throw new Error("`pencil-session end` requires `--pen <path>`.");
       }
+      if (!nodesFile && !force) {
+        throw new Error(
+          "`pencil-session end` requires `--nodes-file <path>` (and `--variables-file <path>` when available). Use `--force` only for emergency lock release."
+        );
+      }
 
       const result = endPencilSession({
         projectPath,

package/lib/icon-aliases.js

@@ -0,0 +1,165 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DEFAULT_ALIASES = {
+  "保险箱": ["vault", "safe box", "archive", "inventory_2"],
+  "金库": ["vault", "safe box", "lock", "inventory_2"],
+  "解密": ["unlock", "lock_open", "key", "verified_user"],
+  "加密": ["lock", "shield", "key", "fingerprint"],
+  "重试": ["refresh", "retry", "sync", "rotate-cw", "arrow-clockwise"],
+  "警告": ["warning", "alert-triangle", "triangle-alert"],
+  "错误": ["error", "x-circle", "circle-x"],
+  "成功": ["check_circle", "check-circle", "circle-check"],
+  "设置": ["settings", "tune", "sliders", "sliders-horizontal"],
+  "首页": ["home", "house"],
+  "用户": ["person", "user", "account", "profile"],
+  "账户": ["person", "user", "account", "profile"],
+  "通知": ["notifications", "bell"],
+  "上传": ["upload", "cloud_upload", "cloud-upload", "upload-cloud"],
+  "下载": ["download", "cloud_download", "cloud-download", "download-cloud"],
+  "搜索": ["search", "magnifying-glass"],
+  "返回": ["chevron_left", "chevron-left", "caret-left", "arrow-left"],
+  "关闭": ["close", "x", "x-circle"],
+  "删除": ["delete", "trash", "trash-2"],
+  "确认": ["check", "done", "check_circle", "check-circle"],
+  "客服": ["headset", "support_agent", "message-circle", "chat"],
+  "客服消息": ["headset", "support_agent", "message-circle", "chat"]
+};
+
+function normalize(text) {
+  return String(text || "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[_/]+/g, " ")
+    .replace(/[^\p{L}\p{N}\s-]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function tokenize(text) {
+  const normalized = normalize(text);
+  if (!normalized) {
+    return [];
+  }
+  return normalized
+    .split(/[\s-]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function unique(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
+function getDefaultAliasPath(homeDir) {
+  const root = homeDir ? path.resolve(homeDir) : os.homedir();
+  return path.join(root, ".da-vinci", "icon-aliases.json");
+}
+
+function resolveAliasPath(options = {}) {
+  if (options.aliasPath) {
+    return path.resolve(options.aliasPath);
+  }
+  return path.resolve(getDefaultAliasPath(options.homeDir));
+}
+
+function normalizeAliasMap(rawMap) {
+  const normalized = {};
+  for (const [key, values] of Object.entries(rawMap || {})) {
+    const normalizedKey = normalize(key);
+    if (!normalizedKey) {
+      continue;
+    }
+    const normalizedValues = unique(
+      (Array.isArray(values) ? values : [values]).flatMap((value) =>
+        String(value || "")
+          .split(",")
+          .map((entry) => entry.trim())
+      )
+    );
+    if (normalizedValues.length === 0) {
+      continue;
+    }
+    normalized[normalizedKey] = normalizedValues;
+  }
+  return normalized;
+}
+
+function loadIconAliases(options = {}) {
+  const aliasPath = resolveAliasPath(options);
+  const mergedBase = normalizeAliasMap(DEFAULT_ALIASES);
+
+  if (!fs.existsSync(aliasPath)) {
+    return {
+      aliasPath,
+      aliases: mergedBase,
+      loaded: false,
+      source: "default"
+    };
+  }
+
+  const text = fs.readFileSync(aliasPath, "utf8");
+  const parsed = JSON.parse(text);
+  const userAliases = normalizeAliasMap(parsed.aliases || parsed);
+
+  return {
+    aliasPath,
+    aliases: {
+      ...mergedBase,
+      ...userAliases
+    },
+    loaded: true,
+    source: "file"
+  };
+}
+
+function expandQueryWithAliases(query, aliases) {
+  const normalizedQuery = normalize(query);
+  const queryTokens = tokenize(normalizedQuery);
+  const matched = new Map();
+
+  if (!normalizedQuery) {
+    return {
+      extraTokens: [],
+      matchedAliases: []
+    };
+  }
+
+  for (const [aliasKey, aliasValues] of Object.entries(aliases || {})) {
+    if (!aliasKey || !Array.isArray(aliasValues) || aliasValues.length === 0) {
+      continue;
+    }
+
+    const tokenHit = queryTokens.includes(aliasKey);
+    const phraseHit = normalizedQuery === aliasKey || normalizedQuery.includes(aliasKey);
+    if (!tokenHit && !phraseHit) {
+      continue;
+    }
+    matched.set(aliasKey, aliasValues);
+  }
+
+  const extraTokens = unique(
+    Array.from(matched.values()).flatMap((aliasValues) =>
+      aliasValues.flatMap((value) => tokenize(value))
+    )
+  );
+
+  return {
+    extraTokens,
+    matchedAliases: Array.from(matched.entries()).map(([key, values]) => ({
+      key,
+      values
+    }))
+  };
+}
+
+module.exports = {
+  DEFAULT_ALIASES,
+  getDefaultAliasPath,
+  resolveAliasPath,
+  loadIconAliases,
+  expandQueryWithAliases,
+  normalizeAliasMap
+};