@examplary/cli 1.6.0 → 1.9.0

package/README.md

@@ -3,7 +3,7 @@
 This package provides a command-line tool to develop and upload custom question types for
 the Examplary platform.
 
-Read more in the [📘 Developer Documentation](https://developers.examplary.ai/question-types).
+Read more in the [📘 Developer Documentation](https://examplary.ai/developers/question-types).
 
 ## Usage
 

package/dist/commands/preview.d.ts

@@ -0,0 +1,5 @@
+#! /usr/bin/env node
+export declare const previewCommand: (argv: {
+    host: string;
+    key: string;
+}) => Promise<void>;

package/dist/commands/preview.js

@@ -0,0 +1,174 @@
+#! /usr/bin/env node
+import { watch } from "fs";
+import { readFile } from "fs/promises";
+import { createServer as createHttpServer } from "http";
+import { resolve } from "path";
+import { cwd, exit } from "process";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import open from "open";
+import { WebSocketServer } from "ws";
+import { setApiHost, setApiKey } from "../lib/api.js";
+import { buildComponent } from "../lib/bundle.js";
+import { readMetaFile } from "../lib/read-meta.js";
+import { buildStyles } from "../lib/styles.js";
+export const previewCommand = async (argv) => {
+    setApiHost(argv.host);
+    setApiKey(argv.key);
+    const dir = cwd();
+    // Verify a question-type file exists (json or yml)
+    try {
+        await readMetaFile();
+    }
+    catch (e) {
+        console.error(`🚫 ${e.message}`);
+        exit(1);
+    }
+    // Let's start a Vite server to preview the question type
+    const root = resolve(import.meta.dirname, "..", "preview-ui");
+    const app = new Hono();
+    app.get("/api/bundle", async (c) => {
+        const path = c.req.query("path");
+        const sourcemap = c.req.query("sourcemap") === "1";
+        const componentName = c.req.query("componentName");
+        try {
+            const componentOutput = await buildComponent(path);
+            if (sourcemap) {
+                return c.body(componentOutput.sourcemap, 200, {
+                    "Content-Type": "application/json",
+                });
+            }
+            else {
+                const sizeInKb = componentOutput.js.length / 1000;
+                if (sizeInKb > 100) {
+                    console.warn(`⚠️ Component ${componentName} is larger than 100 kB! Consider optimizing it.`);
+                }
+                let output = componentOutput.js;
+                if (componentOutput.sourcemap) {
+                    output += `\n//# sourceMappingURL=/api/bundle?componentName=${componentName}&path=${encodeURIComponent(path || "")}&sourcemap=1`;
+                }
+                return c.body(output, 200, {
+                    "Content-Type": "application/javascript",
+                });
+            }
+        }
+        catch (error) {
+            console.error(`🚫 Error bundling component ${componentName} from ${path}: ${error.message}`);
+            return c.text(`Error bundling component ${componentName}: ${error.message}`, 500);
+        }
+    });
+    app.get("/api/icon", async (c) => {
+        const path = c.req.query("path") || "";
+        const icon = await readFile(resolve(dir, path), "utf-8");
+        return c.body(icon, 200, {
+            "Content-Type": "image/svg+xml",
+        });
+    });
+    app.get("/api/stylesheet", async (c) => {
+        const componentName = c.req.query("componentName");
+        try {
+            const componentOutput = await buildStyles();
+            return c.body(componentOutput || "", 200, {
+                "Content-Type": "text/css",
+            });
+        }
+        catch (error) {
+            console.error(`🚫 Error building CSS for component ${componentName}: ${error.message}`);
+            return c.text(`Error building CSS for component ${componentName}: ${error.message}`, 500);
+        }
+    });
+    app.get("/__reload", async (c) => {
+        if (wss) {
+            wss.clients.forEach((client) => {
+                if (client.readyState === 1) {
+                    // WebSocket.OPEN
+                    client.send(JSON.stringify({ type: "reload" }));
+                }
+            });
+        }
+        return c.body(null, 201);
+    });
+    let wsPort; // WebSocket port will be set when server starts
+    app.get("/", async (c) => {
+        let questionType;
+        try {
+            ({ definition: questionType } = await readMetaFile());
+            questionType.components = questionType.components
+                ? Object.entries(questionType.components).reduce((acc, [componentName, componentPath]) => ({
+                    ...acc,
+                    [componentName]: `/api/bundle?componentName=${componentName}&path=${encodeURIComponent(componentPath)}`,
+                }), {})
+                : questionType.components;
+        }
+        catch (e) {
+            return c.text(`Error reading question type definition: ${e.message}`, 500);
+        }
+        let template = await readFile(resolve(root, "index.html"), "utf-8");
+        // Inject hot reload script
+        const hotReloadScript = `
+      <script>
+        (function() {
+          const wsPort = ${wsPort || "null"};
+          if (wsPort) {
+            const ws = new WebSocket('ws://localhost:' + wsPort);
+            ws.onmessage = function(event) {
+              const data = JSON.parse(event.data);
+              if (data.type === 'reload') {
+                console.log('🔄 Reloading page due to file change...');
+                window.location.reload();
+              }
+            };
+            ws.onopen = function() {
+              console.log('🔗 Hot reload connected');
+            };
+            ws.onclose = function() {
+              console.log('🔌 Hot reload disconnected');
+            };
+            ws.onerror = function(error) {
+              console.log('❌ Hot reload error:', error);
+            };
+          }
+        })();
+      </script>
+    `;
+        template =
+            "<script>window._questionType = " +
+                JSON.stringify(questionType) +
+                `;</script>${template}${hotReloadScript}`;
+        return c.html(template);
+    });
+    app.use("/assets/*", serveStatic({ root }));
+    // Set up file watcher
+    const watchDir = cwd();
+    console.log(`📁 Watching ${watchDir} for changes...`);
+    let wss; // Will be initialized after server starts
+    const watcher = watch(watchDir, { recursive: true }, (filename) => {
+        if (filename && !filename.startsWith(".")) {
+            // Broadcast reload message to all connected clients
+            if (wss) {
+                wss.clients.forEach((client) => {
+                    if (client.readyState === 1) {
+                        // WebSocket.OPEN
+                        client.send(JSON.stringify({ type: "reload" }));
+                    }
+                });
+            }
+        }
+    });
+    // Clean up watcher on process exit
+    process.on("SIGINT", () => {
+        watcher.close();
+        process.exit(0);
+    });
+    serve({ fetch: app.fetch, port: 5777 }, (address) => {
+        const port = address.port;
+        wsPort = port + 1234;
+        const wsServer = createHttpServer();
+        wss = new WebSocketServer({ server: wsServer });
+        wsServer.listen(wsPort);
+        const url = `http://localhost:${port}`;
+        console.log(`🚀 Preview server running at ${url}`);
+        open(url);
+    });
+};

package/dist/commands/upload.d.ts

@@ -0,0 +1,5 @@
+#! /usr/bin/env node
+export declare const uploadCommand: (argv: {
+    host: string;
+    key: string;
+}) => Promise<void>;

package/dist/commands/upload.js

@@ -0,0 +1,138 @@
+#! /usr/bin/env node
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { cwd, exit } from "process";
+import { setApiHost, setApiKey, uploadFile } from "../lib/api.js";
+import { buildComponent } from "../lib/bundle.js";
+import { deepCompileJsonata } from "../lib/jsonata.js";
+import { readMetaFile } from "../lib/read-meta.js";
+import { buildStyles } from "../lib/styles.js";
+export const uploadCommand = async (argv) => {
+    setApiHost(argv.host);
+    setApiKey(argv.key);
+    const dir = cwd();
+    let definition = {};
+    try {
+        ({ definition } = await readMetaFile());
+    }
+    catch (e) {
+        console.error(`🚫 ${e.message}`);
+        exit(1);
+    }
+    console.log(`Uploading question type: ${definition.id}...`);
+    if (!definition.id) {
+        console.error(`🚫 Missing required field: id`);
+        exit(1);
+    }
+    if (!definition.name) {
+        console.error(`🚫 Missing required field: name`);
+        exit(1);
+    }
+    // Validate JSONata expressions in the definition
+    if (definition.export?.qti?.interaction?.options) {
+        try {
+            await deepCompileJsonata(definition.export.qti.interaction.options);
+        }
+        catch (e) {
+            console.error(`🚫 Invalid JSONata expression in export.qti.interaction.options: ${e.message}`);
+            exit(1);
+        }
+    }
+    // Bundle and upload components
+    const components = {};
+    const validComponentTypes = [
+        "settings-area",
+        "assessment",
+        "print",
+        "results",
+    ];
+    for (const [componentType, componentPath] of Object.entries(definition.components || {})) {
+        // Validation
+        if (!validComponentTypes.includes(componentType)) {
+            console.error(`🚫 Invalid component type specified: ${componentType}`);
+            exit(1);
+        }
+        const realPath = resolve(dir, componentPath);
+        if (!realPath) {
+            console.error(`🚫 Missing required file: ${componentPath}`);
+            exit(1);
+        }
+        // Bundle component
+        let componentOutput = { js: "" };
+        try {
+            componentOutput = await buildComponent(realPath);
+            const sizeInKb = componentOutput.js.length / 1000;
+            const sizeHint = `(${sizeInKb.toFixed(2)} kB)`;
+            console.log(`• Bundled component ${componentType} from ${componentPath} ${sizeHint}`);
+            if (sizeInKb > 100) {
+                console.warn(`  ⚠️ Component ${componentType} is larger than 100 kB! Consider optimizing it.`);
+                if (process.env.GITHUB_ACTIONS) {
+                    console.log(`::warning file=${realPath},title=Large component size::Component ${componentType} is larger than 100 kB ${sizeHint}! Consider optimizing it.`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`🚫 Error bundling component ${componentType} from ${componentPath}: ${error.message}`);
+            exit(1);
+        }
+        // Upload source map first if it exists
+        let sourceMapStatement = "";
+        if (componentOutput.sourcemap) {
+            const url = await uploadFile(`component-${componentType}.js.map`, componentOutput.sourcemap, "application/json");
+            sourceMapStatement = `\n//# sourceMappingURL=${url}`;
+        }
+        // Upload component
+        components[componentType] = await uploadFile(`component-${componentType}.js`, componentOutput.js + sourceMapStatement, "application/javascript");
+        console.log(`• Uploaded component ${componentType}`);
+    }
+    definition.components = components;
+    // Upload styles if present
+    if (Object.keys(definition.components).length) {
+        const styles = await buildStyles();
+        if (styles) {
+            definition.stylesheet = await uploadFile("styles.css", styles, "text/css");
+            const sizeInKb = styles.length / 1000;
+            const sizeHint = `(${sizeInKb.toFixed(2)} kB)`;
+            console.log(`• Uploaded styles ${sizeHint}`);
+        }
+    }
+    // Upload icon if specified
+    if (definition.icon) {
+        const iconPath = resolve(dir, definition.icon);
+        let iconContents;
+        try {
+            iconContents = await readFile(iconPath, "utf-8");
+        }
+        catch (error) {
+            console.error(`🚫 Error reading icon file: ${error.message}`);
+            exit(1);
+        }
+        if (!iconContents) {
+            console.error(`🚫 Icon file is empty: ${iconPath}`);
+            exit(1);
+        }
+        definition.icon = await uploadFile("icon.svg", iconContents, "image/svg+xml");
+        console.log(`• Uploaded icon`);
+    }
+    // Upload the main question type definition
+    const res = await fetch(`${argv.host}/question-types`, {
+        headers: {
+            Authorization: `Bearer ${argv.key}`,
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+        body: JSON.stringify(definition),
+    });
+    if (!res.ok) {
+        console.error(`🚫 Uploading question type failed`);
+        try {
+            const errorResponse = await res.json();
+            console.log(errorResponse);
+        }
+        catch (e) {
+            console.log(e);
+        }
+        exit(1);
+    }
+    console.log(`• Finished uploading definition\n`);
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#! /usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,37 @@
+#! /usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { previewCommand } from "./commands/preview.js";
+import { uploadCommand } from "./commands/upload.js";
+yargs()
+    .usage("examplary <cmd> [args]")
+    .command("upload", "Bundle and upload a question type definition", (yargs) => {
+    return yargs
+        .option("key", {
+        type: "string",
+        description: "API key for authentication (uses EXAMPLARY_API_KEY env var if not provided)",
+        default: process.env.EXAMPLARY_API_KEY || "",
+    })
+        .option("host", {
+        type: "string",
+        description: "API host to upload to",
+        default: "https://api.examplary.ai",
+    });
+}, (args) => uploadCommand({ host: args.host, key: args.key }))
+    .command("preview", "Run local development server", (yargs) => {
+    return yargs
+        .option("key", {
+        type: "string",
+        description: "API key for authentication (uses EXAMPLARY_API_KEY env var if not provided)",
+        default: process.env.EXAMPLARY_API_KEY || "",
+    })
+        .option("host", {
+        type: "string",
+        description: "API host to upload to",
+        default: "https://api.examplary.ai",
+    });
+}, (args) => previewCommand({ host: args.host, key: args.key }))
+    .help()
+    .recommendCommands()
+    .demandCommand()
+    .parse(hideBin(process.argv));

package/dist/lib/api.d.ts

@@ -0,0 +1,5 @@
+export declare let API_HOST: string;
+export declare let API_KEY: string;
+export declare const setApiKey: (key: string) => void;
+export declare const setApiHost: (host: string) => void;
+export declare const uploadFile: (fileName: string, fileContents: any, contentType: string) => Promise<any>;

package/dist/lib/api.js

@@ -0,0 +1,47 @@
+import { basename } from "path";
+import { exit } from "process";
+// These get overwritten by the CLI options
+export let API_HOST = "https://api.examplary.ai";
+export let API_KEY = process.env.EXAMPLARY_API_KEY || "";
+export const setApiKey = (key) => {
+    if (!key)
+        return;
+    API_KEY = key;
+};
+export const setApiHost = (host) => {
+    if (!host)
+        return;
+    API_HOST = host;
+};
+export const uploadFile = async (fileName, fileContents, contentType) => {
+    const params = new URLSearchParams();
+    params.append("filename", basename(fileName));
+    params.append("contentType", contentType);
+    params.append("type", "question-type");
+    // Request the upload URL
+    const res = await fetch(`${API_HOST}/media/upload?${params.toString()}`, {
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+        },
+    });
+    if (!res.ok) {
+        const errorText = await res.text();
+        console.error(`🚫 Upload failed: ${errorText}`);
+        exit(1);
+    }
+    // Actually upload the file
+    const { uploadUrl, publicUrl } = await res.json();
+    const uploadRes = await fetch(uploadUrl, {
+        method: "PUT",
+        headers: {
+            "Content-Type": contentType,
+        },
+        body: fileContents,
+    });
+    if (!uploadRes.ok) {
+        const errorText = await uploadRes.text();
+        console.error(`🚫 Upload failed: ${errorText}`);
+        exit(1);
+    }
+    return publicUrl;
+};

package/dist/lib/bundle.d.ts

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

package/dist/lib/bundle.js

@@ -0,0 +1,27 @@
+import { build } from "esbuild";
+export const buildComponent = async (file) => {
+    const res = await build({
+        entryPoints: [file],
+        bundle: true,
+        write: false,
+        minify: true,
+        sourcemap: "inline",
+        platform: "browser",
+        format: "cjs",
+        external: [
+            "@examplary/ui",
+            "react",
+            "react-dom",
+            "react/jsx-runtime",
+            "react-dom/client",
+        ],
+    });
+    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();
+    }
+    return { js, sourcemap };
+};

package/dist/lib/jsonata.d.ts

@@ -0,0 +1 @@
+export declare const deepCompileJsonata: (expression: any) => Promise<any>;

package/dist/lib/jsonata.js

@@ -0,0 +1,26 @@
+import jsonata from "jsonata";
+export const deepCompileJsonata = async (expression) => {
+    if (typeof expression === "string" && expression.startsWith("=")) {
+        try {
+            jsonata(expression.substring(1));
+        }
+        catch (error) {
+            throw new Error(`JSONata evaluation failed for "${expression}": ${error.message}`);
+        }
+    }
+    if (Array.isArray(expression)) {
+        const output = [];
+        for (const o of expression) {
+            output.push(await deepCompileJsonata(o));
+        }
+        return output;
+    }
+    if (typeof expression === "object" && expression !== null) {
+        const result = {};
+        for (const [key, value] of Object.entries(expression)) {
+            result[key] = await deepCompileJsonata(value);
+        }
+        return result;
+    }
+    return expression;
+};

package/dist/lib/read-meta.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads and parses the question-type definition file.
+ * Prefers question-type.json over question-type.yml.
+ */
+export declare const readMetaFile: () => Promise<{
+    definition: {
+        $schema?: string;
+        id?: string;
+        name?: string;
+        components?: Record<string, string>;
+        export?: any;
+        stylesheet?: string;
+        icon?: string;
+    };
+    path: string;
+}>;

package/dist/lib/read-meta.js

@@ -0,0 +1,36 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { cwd } from "process";
+import yaml from "yaml";
+/**
+ * Reads and parses the question-type definition file.
+ * Prefers question-type.json over question-type.yml.
+ */
+export const readMetaFile = async () => {
+    const dir = cwd();
+    const jsonPath = join(dir, "question-type.json");
+    const ymlPath = join(dir, "question-type.yml");
+    // Try JSON first, then YAML
+    for (const { path, parse, format } of [
+        { path: jsonPath, parse: (v) => JSON.parse(v), format: "JSON" },
+        { path: ymlPath, parse: (v) => yaml.parse(v), format: "YAML" },
+    ]) {
+        let contents;
+        try {
+            contents = await readFile(path, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        try {
+            const definition = parse(contents);
+            if (definition.$schema)
+                delete definition.$schema;
+            return { definition, path };
+        }
+        catch (error) {
+            throw new Error(`Invalid ${format} in ${path}: ${error.message}`);
+        }
+    }
+    throw new Error("No question-type.json or question-type.yml found in the current directory");
+};

package/dist/lib/styles.d.ts

@@ -0,0 +1 @@
+export declare const buildStyles: () => Promise<string | null>;

package/dist/lib/styles.js

@@ -0,0 +1,24 @@
+import { createRequire } from "module";
+import path from "path";
+import tailwindcss from "@tailwindcss/postcss";
+import postcss from "postcss";
+const require = createRequire(import.meta.url);
+const tailwindDir = path.dirname(require.resolve("tailwindcss/package.json"));
+export const buildStyles = async () => {
+    const absolutePath = path.resolve(tailwindDir);
+    const inputCSS = `
+    @import "${absolutePath}/theme.css" layer(theme);
+    @import "${absolutePath}/utilities.css" layer(utilities);
+  `;
+    const result = await postcss([
+        tailwindcss({
+            optimize: { minify: true },
+        }),
+    ]).process(inputCSS, { from: "module-css.css" });
+    const utilitiesStyles = result.css.split("@layer utilities")[1].trim();
+    if (utilitiesStyles.length < 5) {
+        return null;
+    }
+    const css = result.css.replace(/@layer /g, "@layer modules_");
+    return css;
+};