@ikas/component-cli 1.4.0-beta.1 → 1.4.0-beta.100

package/dist/commands/dev.js

@@ -1,9 +1,10 @@
 import chalk from "chalk";
 import chokidar from "chokidar";
 import { Command } from "commander";
+import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-import { toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, collectUsedCustomTypeIds, generateComponentFile, generateStylesFile, updateBarrelExport, generateProjectId, generateComponentId, generateUniqueId, buildPropGroupHierarchy, findPropGroup, collectPropGroupIds, movePropGroupInTree, } from "../utils/component-helpers.js";
+import { toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, collectUsedCustomTypeIds, shouldWriteGlobalTypes, generateComponentFile, generateStylesFile, updateBarrelExport, generateProjectId, isValidProjectId, findInvalidComponentIds, generateComponentId, generateUniqueId, buildPropGroupHierarchy, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, } from "../utils/component-helpers.js";
 import { compileAllComponents as compileAllComponentsMulti } from "../utils/compile.js";
 import { transformEsmToWindowGlobals, transformChunkForCanvas, buildChunkMapping, } from "../utils/esm-transform.js";
 import { DevServerWebSocket, } from "../utils/websocket-server.js";
@@ -12,10 +13,20 @@ const DEV_SERVER_PORT = 5201;
 const compiledComponents = new Map();
 const compiledSharedModules = new Map();
 let compiledGlobalStyles;
+// Hashes broadcast on the last cycle, used to compute deltas. Reset only on process
+// startup. Editors compare these hashes (sent on the wire as `contentHash`) against their
+// stored YJS value to decide whether to apply the update — so once we've seen a given hash
+// here, we can safely skip broadcasting it again.
+const lastBroadcastComponentHashes = new Map();
+const lastBroadcastSharedHashes = new Map();
+let lastBroadcastGlobalStyleHash;
 // Cached types list received from the editor via sync-types
 let cachedEditorTypes = null;
 // Cached custom type definitions received from the editor via sync-types (full IType objects)
 let cachedCustomTypes = null;
+// Cached theme global variables received from the editor via sync-types.
+// Drives the ThemeSettingName union in src/global-types.ts.
+let cachedThemeSettings = null;
 const LIBRARY_TYPE_PREFIX = "@ikas/";
 /**
  * Match custom types for a component's props from the cached custom types.
@@ -128,12 +139,23 @@ async function compileAllComponentsForDev(config) {
     if (chunkIds.length > 0) {
         console.log(chalk.cyan(`  Extracted ${chunkIds.length} shared chunk(s)`));
     }
-    // Store global CSS (unscoped)
+    // Store global CSS (unscoped). Preserve `updatedAt` across rebuilds when the compiled
+    // global CSS is byte-identical so the editor only sees a fresh timestamp when the
+    // designer actually changed `global.css` — the publish UI watches this timestamp to
+    // decide whether globals need (re)publishing independently of any code component.
     if (result.globalCss && config.projectId) {
-        compiledGlobalStyles = {
+        const previousHash = computeGlobalStyleHash(compiledGlobalStyles);
+        const previousUpdatedAt = compiledGlobalStyles?.updatedAt;
+        const next = {
             projectId: config.projectId,
             compiledCss: result.globalCss,
         };
+        const nextHash = computeGlobalStyleHash(next);
+        next.updatedAt =
+            nextHash === previousHash && previousUpdatedAt !== undefined
+                ? previousUpdatedAt
+                : Date.now();
+        compiledGlobalStyles = next;
         console.log(chalk.cyan(`  Compiled global styles`));
     }
     else {
@@ -208,6 +230,7 @@ async function compileAllComponentsForDev(config) {
         compiledComponents.set(component.id, data);
         console.log(chalk.green(`  Compiled: ${component.name}`));
     }
+    populateContentHashes();
     return true;
 }
 /**
@@ -267,6 +290,7 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
             : undefined,
     };
     compiledComponents.set(componentId, updated);
+    populateContentHashes();
     return updated;
 }
 /**
@@ -275,6 +299,152 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
 function getAllSharedModules() {
     return Array.from(compiledSharedModules.values());
 }
+function sha256Hex(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Compute `contentHash` for every entry in `compiledSharedModules` and `compiledComponents`,
+ * mutating each entry in place. A component's hash incorporates the hashes of its referenced
+ * shared modules (sorted), so any shared-util change cascades into consumers without
+ * requiring a separate "shared module changed" message — the consumer's own hash already
+ * differs. Global styles are tracked separately via `updatedAt` on the global style payload;
+ * they intentionally do NOT roll into component hashes (designers publish globals as a
+ * standalone unit).
+ */
+function populateContentHashes() {
+    for (const mod of compiledSharedModules.values()) {
+        mod.contentHash = sha256Hex([mod.id, mod.compiledServerJs, mod.compiledClientJs, mod.canvasClientJs, mod.compiledCss].join("\0"));
+    }
+    for (const comp of compiledComponents.values()) {
+        const referencedHashes = (comp.usedSharedModuleIds || [])
+            .slice()
+            .sort()
+            .map((id) => `${id}:${compiledSharedModules.get(id)?.contentHash || ""}`)
+            .join("|");
+        comp.contentHash = sha256Hex([
+            comp.id,
+            comp.name,
+            comp.projectId || "",
+            comp.type || "component",
+            comp.isHeader ? "1" : "0",
+            comp.isFooter ? "1" : "0",
+            comp.compiledServerJs,
+            comp.compiledClientJs,
+            comp.compiledCss,
+            comp.canvasClientJs,
+            JSON.stringify(comp.props),
+            JSON.stringify(comp.propGroups || null),
+            JSON.stringify(comp.configPropGroups || null),
+            JSON.stringify(comp.customTypes || null),
+            (comp.usedSharedModuleIds || []).slice().sort().join(","),
+            referencedHashes,
+        ].join("\0"));
+    }
+}
+function computeGlobalStyleHash(g) {
+    if (!g)
+        return undefined;
+    return sha256Hex([g.projectId, g.compiledCss].join("\0"));
+}
+/**
+ * Build a `component-update` payload's `sharedModules` array for one component: the chunks
+ * the editor needs to resolve this component's imports. We always include the full
+ * transitive set (cheap) so the editor never sees a missing chunk during a partial update.
+ */
+function sharedModulesForComponent(comp) {
+    if (!comp.usedSharedModuleIds || comp.usedSharedModuleIds.length === 0)
+        return undefined;
+    const out = [];
+    for (const id of comp.usedSharedModuleIds) {
+        const mod = compiledSharedModules.get(id);
+        if (mod)
+            out.push(mod);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Diff current compile state against `lastBroadcast*` maps and decide what to send:
+ *
+ * - Nothing changed → no broadcast at all (this is the whole point — quiet rebuilds).
+ * - Exactly one component changed, no deletes, no global change → single
+ *   `component-update` (cheap, no full-state replay on the editor).
+ * - Anything more (multi-component, deletes, global style change) → one bundled
+ *   `initial-state`. We deliberately collapse multi-component changes into ONE message so
+ *   the editor doesn't tick through N sequential `markUpdating` / refresh cycles. The
+ *   editor's `autoSyncToTheme` uses `contentHash` to skip YJS writes for components that
+ *   didn't actually change, so the full-state payload only mutates what really moved.
+ *
+ * Newly-connecting editors always receive a full `initial-state` via `onRequestState` in
+ * websocket-server.ts and are independent of this path.
+ */
+function broadcastCompileDelta(wsServer) {
+    const currentGlobalHash = computeGlobalStyleHash(compiledGlobalStyles);
+    const globalStylesChanged = currentGlobalHash !== lastBroadcastGlobalStyleHash;
+    const changedComponentIds = [];
+    for (const [id, comp] of compiledComponents) {
+        const prev = lastBroadcastComponentHashes.get(id);
+        if (prev !== comp.contentHash)
+            changedComponentIds.push(id);
+    }
+    const deletedComponentIds = [];
+    for (const id of lastBroadcastComponentHashes.keys()) {
+        if (!compiledComponents.has(id))
+            deletedComponentIds.push(id);
+    }
+    let changedSharedCount = 0;
+    for (const [id, mod] of compiledSharedModules) {
+        if (lastBroadcastSharedHashes.get(id) !== mod.contentHash)
+            changedSharedCount++;
+    }
+    const result = {
+        changedComponents: changedComponentIds.length,
+        deletedComponents: deletedComponentIds.length,
+        changedSharedModules: changedSharedCount,
+        globalStylesChanged,
+    };
+    const nothingChanged = changedComponentIds.length === 0 &&
+        deletedComponentIds.length === 0 &&
+        !globalStylesChanged;
+    if (nothingChanged)
+        return result;
+    // Single-component edit fast path: avoid making the editor clear+refill its devComponents
+    // map and run autoSyncToTheme for every component. One targeted update is enough.
+    const canUseSingleUpdate = changedComponentIds.length === 1 &&
+        deletedComponentIds.length === 0 &&
+        !globalStylesChanged;
+    if (canUseSingleUpdate) {
+        const comp = compiledComponents.get(changedComponentIds[0]);
+        wsServer.broadcastComponentUpdate(comp, sharedModulesForComponent(comp));
+        lastBroadcastComponentHashes.set(comp.id, comp.contentHash);
+    }
+    else {
+        for (const id of deletedComponentIds) {
+            wsServer.broadcastComponentDeleted(id);
+            lastBroadcastComponentHashes.delete(id);
+        }
+        wsServer.broadcast({
+            type: "initial-state",
+            payload: {
+                components: getAllComponents(),
+                sharedModules: getAllSharedModules(),
+                globalStyles: compiledGlobalStyles,
+                timestamp: Date.now(),
+            },
+        });
+        lastBroadcastComponentHashes.clear();
+        for (const [id, comp] of compiledComponents) {
+            if (comp.contentHash)
+                lastBroadcastComponentHashes.set(id, comp.contentHash);
+        }
+    }
+    lastBroadcastSharedHashes.clear();
+    for (const [id, mod] of compiledSharedModules) {
+        if (mod.contentHash)
+            lastBroadcastSharedHashes.set(id, mod.contentHash);
+    }
+    lastBroadcastGlobalStyleHash = currentGlobalHash;
+    return result;
+}
 /**
  * Read and return the current config from disk
  */
@@ -294,12 +464,20 @@ function writeConfig(configPath, config) {
 function writeGlobalTypesFile(config) {
     const globalTypesPath = path.resolve(process.cwd(), "src/global-types.ts");
     const usedEnumIds = collectUsedEnumIds(config.components);
-    const content = generateGlobalTypesFile(cachedEditorTypes, cachedCustomTypes, usedEnumIds);
-    // Avoid unnecessary writes (prevents file watcher loops)
-    if (fs.existsSync(globalTypesPath)) {
-        const existing = fs.readFileSync(globalTypesPath, "utf-8");
-        if (existing === content)
-            return;
+    const content = generateGlobalTypesFile(cachedEditorTypes, cachedCustomTypes, usedEnumIds, cachedThemeSettings);
+    // Single read instead of existsSync + readFileSync; absent file reads as null.
+    let existing = null;
+    try {
+        existing = fs.readFileSync(globalTypesPath, "utf-8");
+    }
+    catch {
+        existing = null;
+    }
+    // Skip unnecessary writes (file-watcher loops) and, crucially, don't let the
+    // startup write clobber editor-synced theme globals before the editor has
+    // connected and re-synced them.
+    if (!shouldWriteGlobalTypes(existing, content, cachedThemeSettings != null)) {
+        return;
     }
     fs.writeFileSync(globalTypesPath, content);
 }
@@ -323,7 +501,10 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
     const broadcastConfigChange = (componentId) => {
         const updated = rebuildCompiledComponentFromConfig(getConfig(), componentId);
         if (updated) {
-            wsServer.broadcastComponentUpdate(updated);
+            wsServer.broadcastComponentUpdate(updated, sharedModulesForComponent(updated));
+            if (updated.contentHash) {
+                lastBroadcastComponentHashes.set(updated.id, updated.contentHash);
+            }
         }
     };
     return {
@@ -342,6 +523,12 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             if (config.components.some((c) => c.name === pascalName)) {
                 throw new Error(`Component "${pascalName}" already exists`);
             }
+            // No `!` assertion: the config may have been hot-reloaded since startup, and
+            // minting with a missing/malformed projectId writes a corrupt component id
+            // into ikas.config.json that later publishes verbatim.
+            if (!config.projectId || !isValidProjectId(config.projectId)) {
+                throw new Error("Invalid or missing projectId in ikas.config.json — restore the generated value and restart the dev server");
+            }
             const componentId = generateComponentId(config.projectId);
             const componentDir = path.resolve(process.cwd(), `src/components/${pascalName}`);
             // Create directory and files
@@ -395,6 +582,14 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                     }
                 }
             }
+            if (prop.filteredComponentIds && prop.filteredComponentIds.length > 0) {
+                const { unknown } = validateFilteredComponentIds(prop.filteredComponentIds, config.components);
+                if (unknown.length > 0) {
+                    throw new Error(`Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+                        `Component ids are opaque and cannot be derived from names. ` +
+                        `Known components: ${config.components.map((c) => `${c.name} (${c.id})`).join(", ")}.`);
+                }
+            }
             component.props.push(prop);
             writeConfig(configPath, config);
             setConfig(config);
@@ -415,6 +610,14 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             if (propIndex === -1) {
                 throw new Error(`Prop "${propName}" not found on ${component.name}`);
             }
+            if (prop.filteredComponentIds && prop.filteredComponentIds.length > 0) {
+                const { unknown } = validateFilteredComponentIds(prop.filteredComponentIds, config.components);
+                if (unknown.length > 0) {
+                    throw new Error(`Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+                        `Component ids are opaque and cannot be derived from names. ` +
+                        `Known components: ${config.components.map((c) => `${c.name} (${c.id})`).join(", ")}.`);
+                }
+            }
             component.props[propIndex] = prop;
             writeConfig(configPath, config);
             setConfig(config);
@@ -685,8 +888,10 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             regenerateAllComponentTypes(config);
             console.log(chalk.green(`  Deleted enum: ${removed.name} (${enumId})`));
         },
-        onSyncTypes: (types, customTypes) => {
+        onSyncTypes: (types, customTypes, themeSettings) => {
             cachedEditorTypes = types;
+            if (themeSettings)
+                cachedThemeSettings = themeSettings;
             // Merge incoming custom types with existing ones instead of replacing.
             // Custom types belong to the code component project and should not be
             // lost when a different editor project connects.
@@ -765,6 +970,27 @@ async function startDevServer(opts = {}) {
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log(chalk.yellow(`  Auto-generated projectId: ${config.projectId}`));
     }
+    else if (!isValidProjectId(config.projectId)) {
+        // A malformed projectId (hand-edited config) breaks the editor's republish
+        // stability: published/local id prefixes stop matching and every publish
+        // INSERTs duplicate design elements. Fail fast instead of corrupting data.
+        console.error(chalk.red(`Error: invalid projectId "${config.projectId}" in ikas.config.json`));
+        console.error(chalk.gray("projectId must be at least 6 alphanumeric characters (no '-' or '_'). " +
+            "Restore the original generated value — do not hand-edit it."));
+        process.exit(1);
+    }
+    // Component ids carry the same prefix/suffix contract as projectId; the dev
+    // server syncs them into the editor (and from there into themes), so a
+    // hand-edited id must be rejected before the server starts.
+    const invalidComponents = findInvalidComponentIds(config.components);
+    if (invalidComponents.length > 0) {
+        console.error(chalk.red("Error: invalid component id(s) in ikas.config.json:"));
+        invalidComponents.forEach((c) => {
+            console.error(chalk.red(`  - "${c.id}"${c.name ? ` (${c.name})` : ""}`));
+        });
+        console.error(chalk.gray("Component ids are generated — restore the original values; do not hand-edit them."));
+        process.exit(1);
+    }
     console.log(chalk.cyan("\n  ikas Component Dev Server\n"));
     console.log(chalk.gray(`  Project: ${config.name}`));
     console.log(chalk.gray(`  Components: ${config.components.length}\n`));
@@ -792,6 +1018,18 @@ async function startDevServer(opts = {}) {
     // Initial compilation of all components (multi-entry with code splitting)
     console.log(chalk.cyan("  Compiling components..."));
     await compileAllComponentsForDev(config);
+    // Seed the broadcast-hash maps so the first delta-broadcast after startup doesn't replay
+    // the initial state — newly-connecting editors get a full `initial-state` directly via
+    // `onRequestState`, independent of the delta path.
+    for (const [id, comp] of compiledComponents) {
+        if (comp.contentHash)
+            lastBroadcastComponentHashes.set(id, comp.contentHash);
+    }
+    for (const [id, mod] of compiledSharedModules) {
+        if (mod.contentHash)
+            lastBroadcastSharedHashes.set(id, mod.contentHash);
+    }
+    lastBroadcastGlobalStyleHash = computeGlobalStyleHash(compiledGlobalStyles);
     console.log("");
     // Start WebSocket server
     const wsServer = new DevServerWebSocket(DEV_SERVER_PORT);
@@ -832,16 +1070,15 @@ async function startDevServer(opts = {}) {
             console.log(chalk.yellow(`  Recompiling all (triggered by: ${triggeredBy})...`));
             const success = await compileAllComponentsForDev(config);
             if (success) {
-                // Send full state to all connected editors
-                wsServer.broadcast({
-                    type: "initial-state",
-                    payload: {
-                        components: getAllComponents(),
-                        sharedModules: getAllSharedModules(),
-                        globalStyles: compiledGlobalStyles,
-                        timestamp: Date.now(),
-                    },
-                });
+                const delta = broadcastCompileDelta(wsServer);
+                if (delta.changedComponents === 0 &&
+                    delta.deletedComponents === 0 &&
+                    !delta.globalStylesChanged) {
+                    console.log(chalk.gray("  No editor-visible changes (skipped broadcast)"));
+                }
+                else {
+                    console.log(chalk.cyan(`  Broadcast delta: ${delta.changedComponents} changed, ${delta.deletedComponents} deleted, ${delta.changedSharedModules} shared chunks changed${delta.globalStylesChanged ? ", globals updated" : ""}`));
+                }
             }
             else {
                 // Broadcast error for the triggering component if identifiable
@@ -858,20 +1095,33 @@ async function startDevServer(opts = {}) {
         if (normalizedPath === configPath) {
             console.log(chalk.yellow("\n  Config changed, reloading..."));
             try {
-                config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                const reloaded = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                // The startup guards validated projectId/component ids once; a hot-reload
+                // must not smuggle a hand-edited value past them — a malformed id reaching
+                // `generateComponentId` or chunk namespacing corrupts republish matching.
+                // Keep the session's validated projectId if the key was removed; reject the
+                // reload outright (previous config stays active) on invalid values.
+                if (!reloaded.projectId) {
+                    reloaded.projectId = config.projectId;
+                }
+                else if (!isValidProjectId(reloaded.projectId)) {
+                    console.error(chalk.red(`  Ignoring config reload: invalid projectId "${reloaded.projectId}". `) +
+                        chalk.gray("Restore the original generated value — previous config stays active."));
+                    return;
+                }
+                const reloadedInvalidComponents = findInvalidComponentIds(reloaded.components ?? []);
+                if (reloadedInvalidComponents.length > 0) {
+                    console.error(chalk.red(`  Ignoring config reload: invalid component id(s): ${reloadedInvalidComponents
+                        .map((c) => `"${c.id}"`)
+                        .join(", ")}. `) + chalk.gray("Restore the original generated values — previous config stays active."));
+                    return;
+                }
+                config = reloaded;
                 cachedCustomTypes = config.customTypes || [];
                 writeGlobalTypesFile(config);
                 await compileAllComponentsForDev(config);
-                // Send full state to all connected editors
-                wsServer.broadcast({
-                    type: "initial-state",
-                    payload: {
-                        components: getAllComponents(),
-                        sharedModules: getAllSharedModules(),
-                        globalStyles: compiledGlobalStyles,
-                        timestamp: Date.now(),
-                    },
-                });
+                const delta = broadcastCompileDelta(wsServer);
+                console.log(chalk.cyan(`  Config reload delta: ${delta.changedComponents} changed, ${delta.deletedComponents} deleted, ${delta.changedSharedModules} shared chunks changed${delta.globalStylesChanged ? ", globals updated" : ""}`));
             }
             catch (e) {
                 console.error(chalk.red("  Failed to reload config"));
@@ -898,6 +1148,23 @@ async function startDevServer(opts = {}) {
             const entryPath = path.resolve(process.cwd(), component.entry);
             if (!fs.existsSync(entryPath)) {
                 compiledComponents.delete(component.id);
+                // Sync ikas.config.json: remove the component entry and strip any orphaned
+                // filteredComponentIds references in remaining components' props. Write config
+                // before broadcasting so an editor requesting state sees the post-delete view.
+                const idx = config.components.findIndex((c) => c.id === component.id);
+                if (idx !== -1) {
+                    config.components.splice(idx, 1);
+                    for (const remaining of config.components) {
+                        for (const prop of remaining.props || []) {
+                            if (!prop.filteredComponentIds)
+                                continue;
+                            prop.filteredComponentIds = prop.filteredComponentIds.filter((id) => id !== component.id);
+                            if (prop.filteredComponentIds.length === 0)
+                                delete prop.filteredComponentIds;
+                        }
+                    }
+                    writeConfig(configPath, config);
+                }
                 wsServer.broadcastComponentDeleted(component.id);
                 console.log(chalk.red(`  Component removed: ${component.name}`));
             }