@examplary/cli 1.13.1 → 1.15.0

package/README.md

@@ -25,6 +25,10 @@ You'll be required to pass a `--key` argument with your API key, which you can
 obtain from your Examplary account settings. You can also set the `EXAMPLARY_API_KEY`
 environment variable to avoid passing the key every time.
 
+A `README.md` and `preview.png` in the same directory are uploaded as the question type's
+documentation and preview image, along with any translations named by language code, like
+`README.nl.md` or `preview.nl.png`.
+
 ## Validating
 
 To run all of the pre-upload checks without uploading anything, use:

package/dist/commands/upload.js

@@ -1,10 +1,29 @@
 #! /usr/bin/env node
-import { readFile } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import { join } from "path";
 import { cwd, exit } from "process";
 import { setApiHost, setApiKey, uploadFile } from "../lib/api.js";
 import { readJsonOrYamlFile, readMetaFile } from "../lib/read-meta.js";
 import { isValid, printValidationResult, validateDefinition, } from "../lib/validate.js";
+/**
+ * Uploads e.g. `README.md` (English) and its translations like `README.nl.md`,
+ * returning their URLs keyed by language code.
+ */
+const uploadLocalizedFiles = async (dir, baseName, extension, contentType) => {
+    const pattern = new RegExp(`^${baseName}(?:\\.([a-z]{2}))?\\.${extension}$`);
+    const urls = {};
+    for (const file of await readdir(dir)) {
+        const match = file.match(pattern);
+        if (!match)
+            continue;
+        const contents = await readFile(join(dir, file));
+        if (!contents.length)
+            continue;
+        urls[match[1] || "en"] = await uploadFile(file, contents, contentType);
+        console.log(`• Uploaded ${file}`);
+    }
+    return Object.keys(urls).length ? urls : undefined;
+};
 export const uploadCommand = async (argv) => {
     setApiHost(argv.host);
     setApiKey(argv.key);
@@ -38,6 +57,19 @@ export const uploadCommand = async (argv) => {
         console.log(`• Uploaded component ${componentType}`);
     }
     definition.components = components;
+    // Upload the bundled functions
+    const functions = {};
+    for (const [functionName, output] of Object.entries(result.functions)) {
+        // Upload source map first if it exists
+        let sourceMapStatement = "";
+        if (output.sourcemap) {
+            const url = await uploadFile(`function-${functionName}.js.map`, output.sourcemap, "application/json");
+            sourceMapStatement = `\n//# sourceMappingURL=${url}`;
+        }
+        functions[functionName] = await uploadFile(`function-${functionName}.js`, output.js + sourceMapStatement, "application/javascript");
+        console.log(`• Uploaded function ${functionName}`);
+    }
+    definition.functions = functions;
     // Upload styles if present
     if (result.styles) {
         definition.stylesheet = await uploadFile("styles.css", result.styles, "text/css");
@@ -49,18 +81,10 @@ export const uploadCommand = async (argv) => {
         definition.icon = await uploadFile("icon.svg", result.iconContents, "image/svg+xml");
         console.log(`• Uploaded icon`);
     }
-    // Upload the README if present
-    const readme = await readFile(join(dir, "README.md"), "utf-8").catch(() => null);
-    if (readme) {
-        definition.readme = await uploadFile("README.md", readme, "text/markdown");
-        console.log(`• Uploaded README`);
-    }
-    // Upload the preview image if present
-    const previewImage = await readFile(join(dir, "preview.png")).catch(() => null);
-    if (previewImage) {
-        definition.previewImage = await uploadFile("preview.png", previewImage, "image/png");
-        console.log(`• Uploaded preview image`);
-    }
+    definition.readmeUrls = await uploadLocalizedFiles(dir, "README", "md", "text/markdown");
+    definition.readme = definition.readmeUrls?.en;
+    definition.previewImageUrls = await uploadLocalizedFiles(dir, "preview", "png", "image/png");
+    definition.previewImage = definition.previewImageUrls?.en;
     // Upload the preview data if present, always converted to JSON
     try {
         const preview = await readJsonOrYamlFile(dir, "preview");

package/dist/lib/bundle.d.ts

@@ -1,4 +1,10 @@
 export declare const buildComponent: (file: string) => Promise<{
     js: string;
     sourcemap: string;
+    sha256: string;
+}>;
+export declare const buildFunction: (file: string) => Promise<{
+    js: string;
+    sourcemap: string;
+    sha256: string;
 }>;

package/dist/lib/bundle.js

@@ -1,4 +1,8 @@
+import { createHash } from "crypto";
 import { build } from "esbuild";
+const calculateHash = (compiled) => {
+    return createHash("sha256").update(compiled).digest("hex");
+};
 export const buildComponent = async (file) => {
     const res = await build({
         entryPoints: [file],
@@ -23,5 +27,28 @@ export const buildComponent = async (file) => {
         sourcemap = Buffer.from(js.split(sourceMapStatement)[1].trim(), "base64").toString("utf-8");
         js = js.split(sourceMapStatement)[0].trim();
     }
-    return { js, sourcemap };
+    const sha256 = calculateHash(js);
+    return { js, sourcemap, sha256 };
+};
+export const buildFunction = async (file) => {
+    const res = await build({
+        entryPoints: [file],
+        bundle: true,
+        write: false,
+        minify: true,
+        sourcemap: "inline",
+        platform: "neutral",
+        mainFields: ["module", "main"],
+        format: "iife",
+        globalName: "userFunction",
+    });
+    let js = res.outputFiles[0].text;
+    let sourcemap = "";
+    const sourceMapStatement = "\n//# sourceMappingURL=data:application/json;base64,";
+    if (js.includes(sourceMapStatement)) {
+        sourcemap = Buffer.from(js.split(sourceMapStatement)[1].trim(), "base64").toString("utf-8");
+        js = js.split(sourceMapStatement)[0].trim();
+    }
+    const sha256 = calculateHash(js);
+    return { js, sourcemap, sha256 };
 };

package/dist/lib/validate.d.ts

@@ -18,6 +18,8 @@ export type ValidationResult = {
     styles?: string;
     /** Raw icon file contents, present only when an icon is configured. */
     iconContents?: string;
+    /** Bundled function output, keyed by function name, ready to upload. */
+    functions: Record<string, BuiltComponent>;
 };
 /**
  * Runs every check the `upload` command performs, short of actually uploading:

package/dist/lib/validate.js

@@ -1,6 +1,6 @@
 import { readFile } from "fs/promises";
 import { resolve } from "path";
-import { buildComponent } from "./bundle.js";
+import { buildComponent, buildFunction } from "./bundle.js";
 import { deepCompileJsonata } from "./jsonata.js";
 import { runResponseProcessingTestCases, } from "./response-processing.js";
 import { buildStyles } from "./styles.js";
@@ -20,6 +20,7 @@ export const validateDefinition = async (definition, dir) => {
     const errors = [];
     const warnings = [];
     const bundles = {};
+    const functions = {};
     let styles;
     let iconContents;
     if (!definition.id)
@@ -89,6 +90,21 @@ export const validateDefinition = async (definition, dir) => {
             errors.push(`Error bundling component ${componentType} from ${componentPath}: ${error.message}`);
         }
     }
+    // Bundle functions to confirm they build and to capture their output
+    for (const [functionName, functionPath] of Object.entries(definition.functions || {})) {
+        const realPath = resolve(dir, functionPath);
+        try {
+            const output = await buildFunction(realPath);
+            functions[functionName] = output;
+            const sizeInKb = output.js.length / 1000;
+            if (sizeInKb > 100) {
+                errors.push(`Function ${functionName} is larger than the 100 kB limit (${sizeInKb.toFixed(2)} kB)`);
+            }
+        }
+        catch (error) {
+            errors.push(`Error bundling function ${functionName} from ${functionPath}: ${error.message}`);
+        }
+    }
     // Build styles if any components are present
     if (Object.keys(bundles).length) {
         styles = (await buildStyles()) ?? undefined;
@@ -106,7 +122,15 @@ export const validateDefinition = async (definition, dir) => {
             errors.push(`Icon file is empty: ${iconPath}`);
         }
     }
-    return { errors, warnings, testCaseResults, bundles, styles, iconContents };
+    return {
+        errors,
+        warnings,
+        testCaseResults,
+        bundles,
+        functions,
+        styles,
+        iconContents,
+    };
 };
 /** Whether the definition is safe to upload. */
 export const isValid = (result) => result.errors.length === 0 && result.testCaseResults.every((r) => r.passed);
@@ -116,6 +140,10 @@ export const printValidationResult = (result) => {
         const sizeInKb = (output.js.length / 1000).toFixed(2);
         console.log(`• Bundled component ${componentType} (${sizeInKb} kB)`);
     }
+    for (const [functionName, output] of Object.entries(result.functions)) {
+        const sizeInKb = (output.js.length / 1000).toFixed(2);
+        console.log(`• Bundled function ${functionName} (${sizeInKb} kB)`);
+    }
     for (const warning of result.warnings) {
         console.warn(`  ⚠️ ${warning.message}`);
         if (warning.file && process.env.GITHUB_ACTIONS) {