@examplary/cli 1.15.0 → 1.17.0

package/dist/lib/build-app.js

@@ -0,0 +1,179 @@
+import { createHash } from "crypto";
+import { access, mkdir, readFile } from "fs/promises";
+import { tmpdir } from "os";
+import { basename, dirname, extname, join, resolve } from "path";
+import { pathToFileURL } from "url";
+import { AppSchema } from "@examplary/schemas";
+import { build } from "esbuild";
+import { buildQuestionType } from "./build-question-type.js";
+import { buildComponent, splitInlineSourcemap } from "./bundle.js";
+import { buildStyles } from "./styles.js";
+const CONTENT_TYPES = {
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".md": "text/markdown",
+    ".json": "application/json",
+};
+const APP_FILES = ["app.ts", "app.js", "app.mjs"];
+const sha256 = (contents) => createHash("sha256").update(contents).digest("hex");
+export const findAppFile = async (dir) => {
+    for (const name of APP_FILES) {
+        const file = resolve(dir, name);
+        try {
+            await access(file);
+            return file;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error(`No ${APP_FILES.join(", ")} found in ${dir}`);
+};
+/** Evaluates the app module in Node, returning the definition `defineApp()` built. */
+export const loadAppDefinition = async (file) => {
+    const outdir = join(tmpdir(), "examplary-cli");
+    await mkdir(outdir, { recursive: true });
+    const outfile = join(outdir, `${sha256(file).slice(0, 12)}.mjs`);
+    await build({
+        entryPoints: [file],
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node22",
+        outfile,
+        banner: {
+            js: `import { createRequire } from "module"; const require = createRequire(import.meta.url);`,
+        },
+        logLevel: "silent",
+    });
+    const module = await import(`${pathToFileURL(outfile).href}?t=${Date.now()}`);
+    if (typeof module.default?.toDefinition !== "function") {
+        throw new Error(`${file} has to default-export defineApp()`);
+    }
+    return module.default.toDefinition();
+};
+/**
+ * Bundles the app for the sandbox, which only offers standard JavaScript and
+ * `fetch`: a script defining `examplaryApp`, whose default export runs a hook.
+ */
+export const buildServerBundle = async (file) => {
+    const result = await build({
+        stdin: {
+            contents: `import app from ${JSON.stringify(file)};
+export default (input) => app.runHook(input);`,
+            resolveDir: dirname(file),
+        },
+        bundle: true,
+        platform: "neutral",
+        mainFields: ["module", "main"],
+        format: "iife",
+        globalName: "examplaryApp",
+        target: "es2020",
+        minify: true,
+        sourcemap: "inline",
+        write: false,
+        logLevel: "silent",
+    });
+    return splitInlineSourcemap(result.outputFiles[0].text);
+};
+/** Uploads a file the app refers to by a relative path; URLs pass through. */
+const uploadPath = async (dir, path, upload) => {
+    if (/^https?:\/\//.test(path))
+        return path;
+    const contents = await readFile(resolve(dir, path));
+    const contentType = CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+    return upload(basename(path), contents, contentType);
+};
+/** Like `uploadPath`, for a path or an object of paths by language. */
+export const uploadTranslatablePath = async (dir, value, upload) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string")
+        return uploadPath(dir, value, upload);
+    const entries = await Promise.all(Object.entries(value).map(async ([language, path]) => [
+        language,
+        await uploadPath(dir, path, upload),
+    ]));
+    return Object.fromEntries(entries);
+};
+/**
+ * Uploads a bundle's source map, then the bundle pointing at it, for readable
+ * reviews and errors. Its digest pins the reviewed code: whatever runs it checks it.
+ */
+const uploadBundle = async (name, { js, sourcemap }, upload) => {
+    const sourcemapUrl = sourcemap && (await upload(`${name}.map`, sourcemap, "application/json"));
+    const contents = sourcemapUrl
+        ? `${js}\n//# sourceMappingURL=${sourcemapUrl}`
+        : js;
+    return {
+        url: await upload(name, contents, "application/javascript"),
+        sha256: sha256(contents),
+    };
+};
+const uploadComponent = async (dir, { id, path, translations }, upload) => {
+    const bundle = await buildComponent(resolve(dir, path));
+    return {
+        id,
+        ...(await uploadBundle(`${id}.js`, bundle, upload)),
+        translations,
+    };
+};
+/** The Tailwind classes the app's components use, which the dashboard loads with them. */
+const uploadStyles = async (dir, upload) => {
+    const css = await buildStyles(dir);
+    return css ? upload("styles.css", css, "text/css") : undefined;
+};
+const uploadAsset = async (dir, { id, path }, upload) => ({
+    id,
+    url: await uploadPath(dir, path, upload),
+    sha256: sha256(await readFile(resolve(dir, path))),
+});
+/**
+ * Turns the app in `file` into the manifest `POST /apps` accepts: files
+ * uploaded, components and hooks bundled, and hooks listed by ID. Throws when
+ * the result isn't a valid app.
+ */
+export const buildAppManifest = async (file, definition, uploadFile) => {
+    const { hooks, components, assets, questionTypes, ...app } = definition;
+    const dir = dirname(file);
+    // What the app consists of, without the uploads' fresh URLs, so the API can
+    // tell an unchanged upload apart
+    const digests = [];
+    const upload = (fileName, contents, contentType) => {
+        const withoutUrls = typeof contents === "string"
+            ? contents.replace(/\n\/\/# sourceMappingURL=\S+$/, "")
+            : contents;
+        digests.push(`${fileName}:${sha256(withoutUrls)}`);
+        return uploadFile(fileName, contents, contentType);
+    };
+    const server = hooks.length &&
+        (await uploadBundle("server.js", await buildServerBundle(file), upload));
+    const manifest = {
+        ...app,
+        icon: await uploadTranslatablePath(dir, app.icon, upload),
+        readme: await uploadTranslatablePath(dir, app.readme, upload),
+        previewImage: await uploadTranslatablePath(dir, app.previewImage, upload),
+        hooks: hooks.map(({ id }) => ({ id })),
+        server: server ? server.url : undefined,
+        serverSha256: server ? server.sha256 : undefined,
+        components: await Promise.all(components.map((component) => uploadComponent(dir, component, upload))),
+        stylesheet: components.length ? await uploadStyles(dir, upload) : undefined,
+        assets: await Promise.all(assets.map((asset) => uploadAsset(dir, asset, upload))),
+        questionTypes: [],
+    };
+    // One after the other, as each bundles a few components and runs its test cases
+    for (const questionType of questionTypes ?? []) {
+        manifest.questionTypes.push(await buildQuestionType(questionType, dir, upload));
+    }
+    manifest.contentSha256 = sha256([JSON.stringify(definition), ...digests.sort()].join("\n"));
+    const parsed = AppSchema.safeParse(manifest);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "app"}: ${issue.message}`);
+        throw new Error(`Invalid app definition:\n${issues.join("\n")}`);
+    }
+    return manifest;
+};

package/dist/lib/build-current-app.d.ts

@@ -0,0 +1,4 @@
+import { Uploader } from "./build-app.js";
+export declare const dryUpload: Uploader;
+/** Builds the app in the current directory, exiting on any error so a partial app is never published. */
+export declare const buildCurrentApp: (upload: Uploader, quiet?: boolean) => Promise<Record<string, any>>;

package/dist/lib/build-current-app.js

@@ -0,0 +1,21 @@
+import { cwd, exit } from "process";
+import { buildAppManifest, findAppFile, loadAppDefinition, } from "./build-app.js";
+export const dryUpload = async (fileName) => `https://validate.invalid/${fileName}`;
+/** Builds the app in the current directory, exiting on any error so a partial app is never published. */
+export const buildCurrentApp = async (upload, quiet = false) => {
+    try {
+        const file = await findAppFile(cwd());
+        const definition = await loadAppDefinition(file);
+        if (!quiet)
+            console.log(`Building app: ${definition.id}...`);
+        const manifest = await buildAppManifest(file, definition, upload);
+        if (!quiet) {
+            console.log(`• Bundled ${manifest.components.length} component(s), ${manifest.hooks.length} hook(s) and ${manifest.questionTypes.length} question type(s)`);
+        }
+        return manifest;
+    }
+    catch (e) {
+        console.error(`🚫 ${e.message}`);
+        exit(1);
+    }
+};

package/dist/lib/build-question-type.d.ts

@@ -0,0 +1,8 @@
+import type { Uploader } from "./build-app.js";
+/**
+ * Checks a question type of an app (incl. its response processing test cases),
+ * bundles its components, and uploads them with its icon, README
+ * and preview image, all by paths relative to the app's directory `dir`.
+ * Returns the definition `POST /apps` takes.
+ */
+export declare const buildQuestionType: (questionType: Record<string, any>, dir: string, uploadFile: Uploader) => Promise<Record<string, any>>;

package/dist/lib/build-question-type.js

@@ -0,0 +1,48 @@
+import { uploadTranslatablePath } from "./build-app.js";
+import { isValid, printValidationResult, validateDefinition, } from "./validate.js";
+/** Uploads a bundle, with its source map next to it. */
+const uploadBundle = async (name, { js, sourcemap }, upload) => {
+    const sourcemapUrl = sourcemap && (await upload(`${name}.map`, sourcemap, "application/json"));
+    return upload(name, sourcemapUrl ? `${js}\n//# sourceMappingURL=${sourcemapUrl}` : js, "application/javascript");
+};
+/** Uploaded files by language, e.g. a `readme` given as one path or one per language. */
+const uploadByLanguage = async (dir, paths, upload) => {
+    const urls = await uploadTranslatablePath(dir, paths, upload);
+    return typeof urls === "string" ? { en: urls } : urls;
+};
+/**
+ * Checks a question type of an app (incl. its response processing test cases),
+ * bundles its components, and uploads them with its icon, README
+ * and preview image, all by paths relative to the app's directory `dir`.
+ * Returns the definition `POST /apps` takes.
+ */
+export const buildQuestionType = async (questionType, dir, uploadFile) => {
+    // A copy: the app's own definition is hashed without the upload URLs
+    const { readme, previewImage, ...definition } = structuredClone(questionType);
+    // An app has several question types, all with files like `component-print.js`
+    const prefix = definition.id?.split(".").pop();
+    const upload = (name, contents, contentType) => uploadFile(`${prefix}.${name}`, contents, contentType);
+    const result = await validateDefinition(definition, dir);
+    if (!isValid(result)) {
+        printValidationResult(result);
+        throw new Error(`Question type ${definition.id} isn't valid`);
+    }
+    const components = {};
+    for (const [type, output] of Object.entries(result.bundles)) {
+        components[type] = await uploadBundle(`component-${type}.js`, output, upload);
+    }
+    definition.components = components;
+    if (result.styles) {
+        definition.stylesheet = await upload("styles.css", result.styles, "text/css");
+    }
+    if (definition.icon && result.iconContents) {
+        definition.icon = await upload("icon.svg", result.iconContents, "image/svg+xml");
+    }
+    definition.readmeUrls = await uploadByLanguage(dir, readme, upload);
+    definition.readme = definition.readmeUrls?.en;
+    definition.previewImageUrls = await uploadByLanguage(dir, previewImage, upload);
+    definition.previewImage = definition.previewImageUrls?.en;
+    // Test cases have run during validation, they don't need storing
+    delete definition.responseProcessing?.testCases;
+    return definition;
+};

package/dist/lib/bundle.d.ts

@@ -1,9 +1,10 @@
-export declare const buildComponent: (file: string) => Promise<{
+/** A bundle built with an inline source map, as the code and the map apart. */
+export declare const splitInlineSourcemap: (output: string) => {
     js: string;
     sourcemap: string;
     sha256: string;
-}>;
-export declare const buildFunction: (file: string) => Promise<{
+};
+export declare const buildComponent: (file: string) => Promise<{
     js: string;
     sourcemap: string;
     sha256: string;

package/dist/lib/bundle.js

@@ -3,6 +3,14 @@ import { build } from "esbuild";
 const calculateHash = (compiled) => {
     return createHash("sha256").update(compiled).digest("hex");
 };
+/** A bundle built with an inline source map, as the code and the map apart. */
+export const splitInlineSourcemap = (output) => {
+    const [js, encoded] = output.split("\n//# sourceMappingURL=data:application/json;base64,");
+    const sourcemap = encoded
+        ? Buffer.from(encoded.trim(), "base64").toString("utf-8")
+        : "";
+    return { js: js.trim(), sourcemap, sha256: calculateHash(js.trim()) };
+};
 export const buildComponent = async (file) => {
     const res = await build({
         entryPoints: [file],
@@ -20,35 +28,5 @@ export const buildComponent = async (file) => {
             "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();
-    }
-    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 };
+    return splitInlineSourcemap(res.outputFiles[0].text);
 };

package/dist/lib/styles.d.ts

@@ -1 +1,2 @@
-export declare const buildStyles: () => Promise<string | null>;
+/** The Tailwind classes used by the files in `base`, or null when there are none. */
+export declare const buildStyles: (base?: string) => Promise<string | null>;

package/dist/lib/styles.js

@@ -4,7 +4,8 @@ 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 () => {
+/** The Tailwind classes used by the files in `base`, or null when there are none. */
+export const buildStyles = async (base = process.cwd()) => {
     const absolutePath = path.resolve(tailwindDir);
     const inputCSS = `
     @import "${absolutePath}/theme.css" layer(theme);
@@ -12,6 +13,7 @@ export const buildStyles = async () => {
   `;
     const result = await postcss([
         tailwindcss({
+            base,
             optimize: { minify: true },
         }),
     ]).process(inputCSS, { from: "module-css.css" });

package/dist/lib/validate.d.ts

@@ -1,4 +1,4 @@
-import type { QuestionTypeDefinition } from "./read-meta.js";
+import type { QuestionType } from "@examplary/schemas";
 import { TestCaseResult } from "./response-processing.js";
 export type BuiltComponent = {
     js: string;
@@ -18,8 +18,6 @@ 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:
@@ -27,7 +25,7 @@ export type ValidationResult = {
  * response processing test cases. Bundled artifacts are returned so callers can
  * reuse them for an upload without bundling twice.
  */
-export declare const validateDefinition: (definition: QuestionTypeDefinition, dir: string) => Promise<ValidationResult>;
+export declare const validateDefinition: (definition: Partial<QuestionType>, dir: string) => Promise<ValidationResult>;
 /** Whether the definition is safe to upload. */
 export declare const isValid: (result: ValidationResult) => boolean;
 /** Prints warnings, errors, and a test-case summary to the console. */

package/dist/lib/validate.js

@@ -1,6 +1,6 @@
 import { readFile } from "fs/promises";
-import { resolve } from "path";
-import { buildComponent, buildFunction } from "./bundle.js";
+import { dirname, resolve } from "path";
+import { buildComponent } from "./bundle.js";
 import { deepCompileJsonata } from "./jsonata.js";
 import { runResponseProcessingTestCases, } from "./response-processing.js";
 import { buildStyles } from "./styles.js";
@@ -20,7 +20,6 @@ export const validateDefinition = async (definition, dir) => {
     const errors = [];
     const warnings = [];
     const bundles = {};
-    const functions = {};
     let styles;
     let iconContents;
     if (!definition.id)
@@ -90,24 +89,11 @@ 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;
+    // The Tailwind classes used in the folder of its components
+    const [componentPath] = Object.values(definition.components || {});
+    if (Object.keys(bundles).length && componentPath) {
+        styles =
+            (await buildStyles(dirname(resolve(dir, componentPath)))) ?? undefined;
     }
     // Validate the icon file
     if (definition.icon) {
@@ -127,7 +113,6 @@ export const validateDefinition = async (definition, dir) => {
         warnings,
         testCaseResults,
         bundles,
-        functions,
         styles,
         iconContents,
     };
@@ -140,10 +125,6 @@ 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) {

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "@examplary/cli",
-  "description": "Command-line tools for building and publishing Examplary question types.",
+  "description": "Command-line tools for building and publishing Examplary apps.",
   "packageManager": "yarn@4.8.1",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "bin": {
     "exp": "./dist/index.js"
   },
   "scripts": {
     "release": "semantic-release -e semantic-release-monorepo",
-    "build:preview-ui": "vite build",
     "build:js": "tsc --project tsconfig.json",
-    "build": "yarn build:js && yarn build:preview-ui",
-    "dev": "tsx scripts/dev.ts",
+    "build": "yarn build:js",
     "test": "vitest run"
   },
   "publishConfig": {
@@ -22,36 +20,18 @@
   ],
   "dependencies": {
     "@examplary/schemas": "*",
-    "@examplary/ui": "*",
-    "@hono/node-server": "^2.1.3",
     "@tailwindcss/postcss": "^4.3.3",
-    "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.1",
-    "hono": "^4.13.11",
     "jsonata": "^2.2.0",
-    "lucide-react": "^1.39.0",
-    "open": "^11.0.0",
+    "postcss": "^8.5.28",
     "tailwindcss": "^4.2.1",
-    "ws": "^8.22.0",
-    "yaml": "^2.8.3",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",
     "@types/yargs": "^17.0.35",
-    "@vitejs/plugin-react": "^6.0.1",
-    "i18next": "^26.3.4",
-    "i18next-browser-languagedetector": "^8.2.0",
-    "postcss": "^8.5.28",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "react-error-boundary": "^6.1.6",
-    "react-i18next": "^17.0.8",
-    "swr": "^2.3.6",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "use-local-storage": "^3.0.0",
-    "vite": "^8.3.4",
     "vitest": "^5.0.3"
   },
   "homepage": "https://examplary.ai/developers",

package/dist/commands/preview.d.ts

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