@strata-ds/core 2.1.16 → 2.1.18

package/README.md

@@ -524,6 +524,8 @@ const MyComponent = StrataComponentFactory.createComponent(
 	componentData,
 	designSystem,
 );
+```
+
 ## Offline Resilience & Build-Time Fallbacks
 
 `@strata-ds/core` is built to be completely resilient to network outages, CDN downtime, or slow connections using a multi-layered fallback strategy.
@@ -541,18 +543,27 @@ const MyComponent = StrataComponentFactory.createComponent(
 
 Any project using the Strata Design System can enable full offline resilience in three quick steps:
 
-#### Step 1: Generate the Local Snapshot and Fallback CSS
-Run the CLI snapshot tool locally or add it to your project's build process:
-```bash
-npx strata-ds snapshot \
-  --project-id "YOUR_PROJECT_ID" \
-  --cdn-base "https://your-cdn-base-url.cloudfront.net" \
-  --output "./src/data/strata-snapshot.json" \
-  --output-css "./src/styles/strata-fallbacks.css" \
-  --variables-only
+#### Step 1: Configure Auto-Generation in `package.json`
+Simply add a `"strata"` configuration block to your application's `package.json`. The SDK's built-in postinstall hook will automatically fetch the latest snapshot and generate the fallback assets every time you run `npm install`:
+
+```json
+{
+  "name": "your-app",
+  "strata": {
+    "projectId": "YOUR_PROJECT_ID",
+    "snapshotCdnBase": "https://your-cdn-base-url.cloudfront.net",
+    "output": "./src/data/strata-snapshot.json",
+    "outputCss": "./src/styles/strata-fallbacks.css",
+    "variablesOnly": true
+  }
+}
 ```
+
 *(Commit the generated JSON and CSS files to your Git repository as your baseline fallback).*
 
+> 💡 **Manual Generation**: You can also run the CLI snapshot tool manually if needed:
+> `npx strata-ds snapshot --project-id "YOUR_PROJECT_ID" --cdn-base "https://your-cdn-base-url.cloudfront.net" --output "./src/data/strata-snapshot.json" --output-css "./src/styles/strata-fallbacks.css" --variables-only`
+
 #### Step 2: Import Fallback Styles
 Reference the CSS file in your main style entry point (e.g., `src/index.css` or `src/App.css`):
 ```css

package/dist/cli/postinstall.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/postinstall.js

@@ -0,0 +1,141 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function retrieveSnapshot(options) {
+    const { projectId, cdnBase, outputPath, outputCssPath, syncToken, variablesOnly } = options;
+    const base = cdnBase.replace(/\/+$/, '');
+    const snapshotUrl = base.endsWith('/snapshots')
+        ? `${base}/${projectId}/strata.json`
+        : `${base}/snapshots/${projectId}/strata.json`;
+    console.log(`📡 Fetching snapshot from: ${snapshotUrl}`);
+    try {
+        const headers = {};
+        if (syncToken) {
+            headers['Authorization'] = `Bearer ${syncToken}`;
+        }
+        const res = await fetch(snapshotUrl, { headers });
+        if (!res.ok) {
+            throw new Error(`Server returned ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        // Validate shape
+        if (!data || typeof data !== 'object' || typeof data.variables !== 'object') {
+            throw new Error('Invalid snapshot response shape: missing variables');
+        }
+        let snapshotJson = data;
+        if (variablesOnly) {
+            snapshotJson = {
+                variables: data.variables,
+            };
+        }
+        // Write JSON output if requested
+        if (outputPath) {
+            const resolvedOutput = path.resolve(outputPath);
+            fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+            fs.writeFileSync(resolvedOutput, JSON.stringify(snapshotJson, null, 2), 'utf-8');
+            console.log(`✅ Snapshot JSON written to: ${resolvedOutput}`);
+        }
+        // Write CSS output if requested
+        if (outputCssPath) {
+            const resolvedCssOutput = path.resolve(outputCssPath);
+            fs.mkdirSync(path.dirname(resolvedCssOutput), { recursive: true });
+            let cssContent = `/* @strata-ds/core — Auto-generated CSS fallback variables\n`;
+            cssContent += ` * Project: ${projectId}\n`;
+            cssContent += ` * Generated: ${new Date().toISOString()}\n`;
+            cssContent += ` * DO NOT EDIT MANUALLY — regenerate with CLI snapshot tool\n`;
+            cssContent += ` */\n\n`;
+            cssContent += `:root {\n`;
+            const variables = data.variables || {};
+            for (const [key, val] of Object.entries(variables)) {
+                const resolvedVal = val.resolvedValue ?? val.value;
+                cssContent += `  ${key}: ${resolvedVal};\n`;
+            }
+            cssContent += `}\n`;
+            fs.writeFileSync(resolvedCssOutput, cssContent, 'utf-8');
+            console.log(`✅ CSS fallback written to: ${resolvedCssOutput}`);
+        }
+    }
+    catch (error) {
+        console.warn(`⚠️ Warning: Fetch failed: ${error.message || error}`);
+        // If fetch failed, check if output files already exist to degrade gracefully (exit 0)
+        let jsonExists = false;
+        let cssExists = false;
+        if (outputPath && fs.existsSync(path.resolve(outputPath))) {
+            jsonExists = true;
+        }
+        if (outputCssPath && fs.existsSync(path.resolve(outputCssPath))) {
+            cssExists = true;
+        }
+        const requestedOutputs = [];
+        if (outputPath)
+            requestedOutputs.push('JSON');
+        if (outputCssPath)
+            requestedOutputs.push('CSS');
+        const existingOutputs = [];
+        if (jsonExists)
+            existingOutputs.push('JSON');
+        if (cssExists)
+            existingOutputs.push('CSS');
+        if (requestedOutputs.length > 0 && requestedOutputs.length === existingOutputs.length) {
+            console.warn(`ℹ️ Existing output file(s) found. Graceful degradation: exiting 0.`);
+            return;
+        }
+        else {
+            throw new Error('Fetch failed and no existing local outputs found to fall back on.');
+        }
+    }
+}
+
+function findHostPackage() {
+    let currentDir = process.cwd();
+    // Traverse up to find the host application's package.json
+    while (true) {
+        const packagePath = path.join(currentDir, 'package.json');
+        if (fs.existsSync(packagePath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+                if (pkg.name !== '@strata-ds/core' && pkg.strata) {
+                    return { packagePath, rootDir: currentDir, config: pkg.strata };
+                }
+            }
+            catch (e) { }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    return null;
+}
+async function run() {
+    const hostInfo = findHostPackage();
+    if (!hostInfo) {
+        console.log('[Strata] No "strata" configuration block found in host package.json. Skipping auto-snapshot retrieval.');
+        return;
+    }
+    const { rootDir, config } = hostInfo;
+    const { projectId, snapshotCdnBase, output, outputCss, syncToken, variablesOnly } = config;
+    if (!projectId || !snapshotCdnBase) {
+        console.warn('[Strata] Warning: "projectId" and "snapshotCdnBase" are required in package.json "strata" config.');
+        return;
+    }
+    const outputPath = output ? path.resolve(rootDir, output) : undefined;
+    const outputCssPath = outputCss ? path.resolve(rootDir, outputCss) : undefined;
+    console.log(`[Strata] Postinstall: Fetching snapshot for project ${projectId}...`);
+    try {
+        await retrieveSnapshot({
+            projectId,
+            cdnBase: snapshotCdnBase,
+            outputPath,
+            outputCssPath,
+            syncToken,
+            variablesOnly: variablesOnly !== false, // default to true for post-install variable trimming
+        });
+        console.log('✅ [Strata] Postinstall snapshot retrieval complete.');
+    }
+    catch (error) {
+        // Graceful degradation: log warning but do not throw error so install succeeds
+        console.warn(`⚠️ [Strata] Postinstall snapshot failed: ${error.message || error}`);
+    }
+}
+run();

package/dist/cli/retrieve.d.ts

@@ -0,0 +1,9 @@
+export interface RetrieveOptions {
+    projectId: string;
+    cdnBase: string;
+    outputPath?: string;
+    outputCssPath?: string;
+    syncToken?: string;
+    variablesOnly?: boolean;
+}
+export declare function retrieveSnapshot(options: RetrieveOptions): Promise<void>;

package/dist/cli/snapshot.js

@@ -3,50 +3,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-function printHelp() {
-    console.log(`
-Strata Design System Snapshot CLI
-
-Usage:
-  npx strata-ds [options]
-
-Options:
-  --project-id       Strata Project ID (required)
-  --cdn-base         CDN base URL (e.g. https://dx2nhw7wqn4nn.cloudfront.net) (required)
-  --output           Path to write the snapshot JSON file (optional)
-  --output-css       Path to write the CSS fallback file (optional)
-  --sync-token       Authorization Sync Token (optional)
-  --variables-only   Only output variables in the snapshot JSON (optional)
-  --help, -h         Show help
-`);
-}
-async function run() {
-    const args = process.argv.slice(2);
-    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
-        printHelp();
-        process.exit(0);
-    }
-    const getArgValue = (flag) => {
-        const idx = args.indexOf(flag);
-        if (idx !== -1 && idx + 1 < args.length) {
-            return args[idx + 1];
-        }
-        return undefined;
-    };
-    const hasFlag = (flag) => {
-        return args.includes(flag);
-    };
-    const projectId = getArgValue('--project-id');
-    const cdnBase = getArgValue('--cdn-base');
-    const outputPath = getArgValue('--output');
-    const outputCssPath = getArgValue('--output-css');
-    const syncToken = getArgValue('--sync-token');
-    const variablesOnly = hasFlag('--variables-only');
-    if (!projectId || !cdnBase) {
-        console.error('❌ Error: --project-id and --cdn-base are required.');
-        printHelp();
-        process.exit(1);
-    }
+async function retrieveSnapshot(options) {
+    const { projectId, cdnBase, outputPath, outputCssPath, syncToken, variablesOnly } = options;
     const base = cdnBase.replace(/\/+$/, '');
     const snapshotUrl = base.endsWith('/snapshots')
         ? `${base}/${projectId}/strata.json`
@@ -122,12 +80,71 @@ async function run() {
             existingOutputs.push('CSS');
         if (requestedOutputs.length > 0 && requestedOutputs.length === existingOutputs.length) {
             console.warn(`ℹ️ Existing output file(s) found. Graceful degradation: exiting 0.`);
-            process.exit(0);
+            return;
         }
         else {
-            console.error('❌ Error: Fetch failed and no existing local outputs found to fall back on.');
-            process.exit(1);
+            throw new Error('Fetch failed and no existing local outputs found to fall back on.');
         }
     }
 }
+
+function printHelp() {
+    console.log(`
+Strata Design System Snapshot CLI
+
+Usage:
+  npx strata-ds snapshot [options]
+
+Options:
+  --project-id       Strata Project ID (required)
+  --cdn-base         CDN base URL (e.g. https://dx2nhw7wqn4nn.cloudfront.net) (required)
+  --output           Path to write the snapshot JSON file (optional)
+  --output-css       Path to write the CSS fallback file (optional)
+  --sync-token       Authorization Sync Token (optional)
+  --variables-only   Only output variables in the snapshot JSON (optional)
+  --help, -h         Show help
+`);
+}
+async function run() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
+    const getArgValue = (flag) => {
+        const idx = args.indexOf(flag);
+        if (idx !== -1 && idx + 1 < args.length) {
+            return args[idx + 1];
+        }
+        return undefined;
+    };
+    const hasFlag = (flag) => {
+        return args.includes(flag);
+    };
+    const projectId = getArgValue('--project-id');
+    const cdnBase = getArgValue('--cdn-base');
+    const outputPath = getArgValue('--output');
+    const outputCssPath = getArgValue('--output-css');
+    const syncToken = getArgValue('--sync-token');
+    const variablesOnly = hasFlag('--variables-only');
+    if (!projectId || !cdnBase) {
+        console.error('❌ Error: --project-id and --cdn-base are required.');
+        printHelp();
+        process.exit(1);
+    }
+    try {
+        await retrieveSnapshot({
+            projectId,
+            cdnBase,
+            outputPath,
+            outputCssPath,
+            syncToken,
+            variablesOnly,
+        });
+    }
+    catch (error) {
+        console.error(`❌ Error: ${error.message || error}`);
+        process.exit(1);
+    }
+}
 run();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@strata-ds/core",
-	"version": "2.1.16",
+	"version": "2.1.18",
 	"type": "module",
 	"description": "The runtime component library for Strata — design once, sync everywhere.",
 	"homepage": "https://strata.charisol.io",
@@ -25,7 +25,8 @@
 		"build": "rollup -c",
 		"dev": "rollup -c -w",
 		"build:css": "tailwindcss -i ./src/styles.css -o ./dist/styles.css --minify",
-		"prepublishOnly": "npm run build"
+		"prepublishOnly": "npm run build",
+		"postinstall": "node -e \"if (require('fs').existsSync('./dist/cli/postinstall.js')) import('./dist/cli/postinstall.js')\""
 	},
 	"keywords": [
 		"strata",