@examplary/cli 1.14.0 → 1.17.0

package/README.md

@@ -1,36 +1,37 @@
 # Examplary CLI
 
-This package provides a command-line tool to develop and upload custom question types for
-the Examplary platform.
+This package provides a command-line tool to develop and publish apps for the Examplary
+platform, including the question types they provide.
 
-Read more in the [📘 Developer Documentation](https://examplary.ai/developers/question-types).
+Read more in the [📘 Developer Documentation](https://examplary.ai/developers/apps).
 
-## Usage
+## Question types
 
-You can locally develop your custom question types using the Examplary CLI, by
-running the following command in your project directory:
+Question types are published as part of an app, with `app.addCapability(new QuestionType({...}))` from
+[`@examplary/apps`](../apps-runtime/README.md). Their JSONata expressions, response processing
+test cases, components and icon are checked whenever the app is validated or uploaded.
 
-```bash
-npx @examplary/cli preview
-```
+## Apps
 
-To upload your custom question type, run the following command in a directory
-that contains a `question-type.json` or `question-type.yml` file:
+To start a new app:
 
 ```bash
-npx @examplary/cli upload
+npx @examplary/cli init my-app --id com.acme.my-app --name "My app"
 ```
 
-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.
-
-## Validating
+This creates an `app.ts`, and a `package.json` with `validate` and `publish` scripts, and
+installs the dependencies (`--no-install` to skip that).
 
-To run all of the pre-upload checks without uploading anything, use:
+In a directory with an `app.ts` (or `app.js`) that default-exports `defineApp()` from
+[`@examplary/apps`](../apps-runtime/README.md):
 
 ```bash
-npx @examplary/cli validate
+npx @examplary/cli validate   # bundle everything and check the app, without publishing
+npx @examplary/cli publish    # the same, then upload the files and publish the app
+npx @examplary/cli package    # the same, but write the files and app.json to .bundled/
+npx @examplary/cli set-secret NAME value   # set a secret, read in hooks from env
 ```
 
-This verifies required fields, JSONata expressions (including `responseProcessing.condition`), response processing test cases, that components bundle, and the icon file. The same checks run automatically as part of `upload`.
+`publish` and `set-secret` take a `--key` argument with your API key, which you can
+obtain from your Examplary account settings (or the `EXAMPLARY_API_KEY` environment variable),
+and a `--host`.

package/dist/commands/init.d.ts

@@ -0,0 +1,14 @@
+type InitOptions = {
+    id?: string;
+    name?: string;
+};
+/** Creates a new app in `dir`, which has to be empty or not exist yet. */
+export declare const initApp: (dir: string, options?: InitOptions) => Promise<{
+    id: string;
+    name: string;
+}>;
+export declare const initCommand: (argv: InitOptions & {
+    directory?: string;
+    install: boolean;
+}) => Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,103 @@
+import { spawn } from "child_process";
+import { mkdir, readdir, writeFile } from "fs/promises";
+import { basename, join, relative, resolve } from "path";
+import { cwd, env, exit, platform } from "process";
+const latestVersion = async (pkg) => {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return `^${(await res.json()).version}`;
+    }
+    catch {
+        return "latest";
+    }
+};
+const appTs = (id, name) => `import { defineApp } from "@examplary/apps";
+
+const app = defineApp({
+  id: "${id}",
+  name: { en: "${name}" },
+  description: { en: "Describe what your app adds to Examplary" },
+});
+
+export default app;
+`;
+const tsconfig = {
+    compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        jsx: "react-jsx",
+        strict: true,
+        skipLibCheck: true,
+        noEmit: true,
+    },
+};
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** Creates a new app in `dir`, which has to be empty or not exist yet. */
+export const initApp = async (dir, options = {}) => {
+    const files = await readdir(dir).catch(() => []);
+    if (files.some((file) => !file.startsWith("."))) {
+        throw new Error(`${dir} isn't empty`);
+    }
+    const slug = basename(dir)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    const id = options.id ?? `com.example.${slug}`;
+    const name = options.name ??
+        slug.charAt(0).toUpperCase() + slug.slice(1).replace(/-/g, " ");
+    const packageJson = {
+        name: slug,
+        private: true,
+        scripts: {
+            validate: "exp validate",
+            publish: "exp publish",
+        },
+        devDependencies: {
+            "@examplary/apps": await latestVersion("@examplary/apps"),
+            "@examplary/cli": await latestVersion("@examplary/cli"),
+            "@examplary/ui": await latestVersion("@examplary/ui"),
+        },
+    };
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "app.ts"), appTs(id, name));
+    await writeFile(join(dir, "package.json"), json(packageJson));
+    await writeFile(join(dir, "tsconfig.json"), json(tsconfig));
+    await writeFile(join(dir, ".gitignore"), "node_modules\n.bundled\n");
+    return { id, name };
+};
+const install = (dir, packageManager) => new Promise((done) => spawn(packageManager, ["install"], {
+    cwd: dir,
+    stdio: "inherit",
+    shell: platform === "win32",
+})
+    .on("close", (code) => done(code === 0))
+    .on("error", () => done(false)));
+export const initCommand = async (argv) => {
+    const dir = resolve(cwd(), argv.directory ?? ".");
+    // The one that ran the CLI, like npx or yarn dlx
+    const packageManager = env.npm_config_user_agent?.split("/")[0] || "npm";
+    try {
+        const { id, name } = await initApp(dir, argv);
+        const path = relative(cwd(), dir);
+        console.log(`✨ Created ${name} (${id}) in ${dir}\n`);
+        const installed = argv.install && (await install(dir, packageManager));
+        if (argv.install && !installed) {
+            console.log(`\n⚠️ Installing the dependencies failed\n`);
+        }
+        console.log(`Next steps:`);
+        if (path)
+            console.log(`  cd ${path}`);
+        if (!installed)
+            console.log(`  ${packageManager} install`);
+        console.log(`  ${packageManager} run validate`);
+        console.log(`  EXAMPLARY_API_KEY=... ${packageManager} run publish\n`);
+        console.log(`The app's ID can't be changed once it's published, so set it in app.ts first if needed.`);
+    }
+    catch (e) {
+        console.error(`🚫 ${e.message}`);
+        exit(1);
+    }
+};

package/dist/commands/package.d.ts

@@ -0,0 +1 @@
+export declare const packageCommand: () => Promise<void>;

package/dist/commands/package.js

@@ -0,0 +1,16 @@
+import { mkdir, rm, writeFile } from "fs/promises";
+import { join } from "path";
+import { cwd } from "process";
+import { buildCurrentApp } from "../lib/build-current-app.js";
+const PACKAGE_DIR = join(cwd(), ".bundled");
+const localUpload = async (fileName, contents) => {
+    await writeFile(join(PACKAGE_DIR, fileName), contents);
+    return `https://bundled.invalid/${fileName}`;
+};
+export const packageCommand = async () => {
+    await rm(PACKAGE_DIR, { recursive: true, force: true });
+    await mkdir(PACKAGE_DIR);
+    const manifest = await buildCurrentApp(localUpload);
+    await writeFile(join(PACKAGE_DIR, "app.json"), JSON.stringify(manifest, null, 2));
+    console.log(`\n📦 Packaged app in ${PACKAGE_DIR}`);
+};

package/dist/commands/publish.d.ts

@@ -0,0 +1,5 @@
+export declare const publishCommand: (argv: {
+    host: string;
+    key: string;
+    force?: boolean;
+}) => Promise<void>;

package/dist/commands/publish.js

@@ -0,0 +1,57 @@
+import { exit } from "process";
+import { setTimeout } from "timers/promises";
+import { API_HOST, API_KEY, setApiHost, setApiKey, uploadFile, } from "../lib/api.js";
+import { buildCurrentApp, dryUpload } from "../lib/build-current-app.js";
+const appUpload = (fileName, contents, contentType) => uploadFile(fileName, contents, contentType, "app");
+const publishedContentSha256 = async (id) => {
+    const res = await fetch(`${API_HOST}/apps/${id}`, {
+        headers: { Authorization: `Bearer ${API_KEY}` },
+    });
+    return res.ok ? (await res.json()).contentSha256 : undefined;
+};
+// Deploys can upload the default apps before the API that accepts them is live
+const PUBLISH_RETRIES = 20;
+const PUBLISH_RETRY_DELAY_MS = 20000;
+const publish = async (manifest, force, attempt = 0) => {
+    const res = await fetch(`${API_HOST}/apps${force ? "?force=true" : ""}`, {
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+        body: JSON.stringify(manifest),
+    });
+    if (res.status !== 404 || attempt === PUBLISH_RETRIES)
+        return res;
+    console.log(`• The API doesn't accept apps yet, trying again in 20 seconds (${attempt + 1}/${PUBLISH_RETRIES})`);
+    await setTimeout(PUBLISH_RETRY_DELAY_MS);
+    return publish(manifest, force, attempt + 1);
+};
+export const publishCommand = async (argv) => {
+    setApiHost(argv.host);
+    setApiKey(argv.key);
+    // Built without uploading first, to skip uploading every file of an app
+    // that hasn't changed, like the default apps on every deploy
+    const { id, contentSha256 } = await buildCurrentApp(dryUpload, true);
+    if (!argv.force && contentSha256 === (await publishedContentSha256(id))) {
+        console.log(`• Nothing changed since the published version of ${id}\n`);
+        return;
+    }
+    const manifest = await buildCurrentApp(appUpload);
+    console.log(`\nPublishing app: ${manifest.id}...`);
+    const res = await publish(manifest, !!argv.force);
+    if (!res.ok) {
+        console.error(`🚫 Publishing app failed`);
+        console.log(await res.text());
+        exit(1);
+    }
+    const { versionStatus, versionNumber, unchanged } = await res.json();
+    if (unchanged) {
+        console.log(`• Nothing changed since version ${versionNumber} (${versionStatus})\n`);
+    }
+    else {
+        console.log(versionStatus === "pending"
+            ? `• Submitted, this version is used once Examplary has reviewed it\n`
+            : `• Published app\n`);
+    }
+};

package/dist/commands/set-secret.d.ts

@@ -0,0 +1,6 @@
+export declare const setSecretCommand: (argv: {
+    host: string;
+    key: string;
+    name: string;
+    value: string;
+}) => Promise<void>;

package/dist/commands/set-secret.js

@@ -0,0 +1,29 @@
+import { cwd, exit } from "process";
+import { API_HOST, API_KEY, setApiHost, setApiKey } from "../lib/api.js";
+import { findAppFile, loadAppDefinition } from "../lib/build-app.js";
+export const setSecretCommand = async (argv) => {
+    setApiHost(argv.host);
+    setApiKey(argv.key);
+    let appId;
+    try {
+        ({ id: appId } = await loadAppDefinition(await findAppFile(cwd())));
+    }
+    catch (e) {
+        console.error(`🚫 ${e.message}`);
+        exit(1);
+    }
+    const res = await fetch(`${API_HOST}/apps/${appId}/secrets/${argv.name}`, {
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        method: "PUT",
+        body: JSON.stringify({ value: argv.value }),
+    });
+    if (!res.ok) {
+        console.error(`🚫 Setting secret failed`);
+        console.log(await res.text());
+        exit(1);
+    }
+    console.log(`🔑 Set secret ${argv.name} for ${appId}`);
+};

package/dist/commands/validate.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
 export declare const validateCommand: () => Promise<void>;

package/dist/commands/validate.js

@@ -1,23 +1,5 @@
-#!/usr/bin/env node
-import { cwd, exit } from "process";
-import { readMetaFile } from "../lib/read-meta.js";
-import { isValid, printValidationResult, validateDefinition, } from "../lib/validate.js";
+import { buildCurrentApp, dryUpload } from "../lib/build-current-app.js";
 export const validateCommand = async () => {
-    const dir = cwd();
-    let definition = {};
-    try {
-        ({ definition } = await readMetaFile());
-    }
-    catch (e) {
-        console.error(`🚫 ${e.message}`);
-        exit(1);
-    }
-    console.log(`Validating question type: ${definition.id}...`);
-    const result = await validateDefinition(definition, dir);
-    printValidationResult(result);
-    if (!isValid(result)) {
-        console.error(`\n🚫 Validation failed`);
-        exit(1);
-    }
+    await buildCurrentApp(dryUpload);
     console.log(`\n✅ Validation passed`);
 };

package/dist/index.js

@@ -1,39 +1,48 @@
 #! /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";
+import { initCommand } from "./commands/init.js";
+import { packageCommand } from "./commands/package.js";
+import { publishCommand } from "./commands/publish.js";
+import { setSecretCommand } from "./commands/set-secret.js";
 import { validateCommand } from "./commands/validate.js";
+const withApiOptions = (yargs) => 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 connect to",
+    default: "https://api.examplary.ai",
+});
 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("validate", "Validate a question type definition without uploading", (yargs) => yargs, () => validateCommand())
-    .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 }))
+    .command("init [directory]", "Create a new app, in the given or the current directory", (yargs) => withApiOptions(yargs)
+    .positional("directory", { type: "string" })
+    .option("id", {
+    type: "string",
+    description: "The app's ID, like com.acme.gradebook",
+})
+    .option("name", { type: "string", description: "The app's name" })
+    .option("install", {
+    type: "boolean",
+    default: true,
+    description: "Install the dependencies (--no-install to skip)",
+}), (args) => initCommand(args))
+    .command("publish", "Bundle, upload and publish the app in this directory", (yargs) => withApiOptions(yargs).option("force", {
+    type: "boolean",
+    default: false,
+    description: "Publish a new version even when nothing changed",
+}), (args) => publishCommand({ host: args.host, key: args.key, force: args.force }))
+    .command("validate", "Bundle and validate the app without publishing", (yargs) => yargs, () => validateCommand())
+    .command("package", "Bundle the app into a local .bundled directory, for debugging", (yargs) => yargs, () => packageCommand())
+    .command("set-secret <name> <value>", "Set a secret of the app, available to its hooks", (yargs) => withApiOptions(yargs)
+    .positional("name", { type: "string", demandOption: true })
+    .positional("value", { type: "string", demandOption: true }), (args) => setSecretCommand(args))
     .help()
+    .strict()
     .recommendCommands()
     .demandCommand()
     .parse(hideBin(process.argv));

package/dist/lib/api.d.ts

@@ -2,4 +2,4 @@ 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>;
+export declare const uploadFile: (fileName: string, fileContents: any, contentType: string, type?: string) => Promise<any>;

package/dist/lib/api.js

@@ -1,5 +1,6 @@
 import { basename } from "path";
 import { exit } from "process";
+import { setTimeout } from "timers/promises";
 // These get overwritten by the CLI options
 export let API_HOST = "https://api.examplary.ai";
 export let API_KEY = process.env.EXAMPLARY_API_KEY || "";
@@ -13,17 +14,27 @@ export const setApiHost = (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
+// An app uploads every file it consists of, which can add up across apps
+const RATE_LIMIT_RETRIES = 4;
+const RATE_LIMIT_DELAY_MS = 30000;
+const requestUploadUrl = async (params, attempt = 0) => {
     const res = await fetch(`${API_HOST}/media/upload?${params.toString()}`, {
         headers: {
             Authorization: `Bearer ${API_KEY}`,
         },
     });
+    if (res.status !== 429 || attempt === RATE_LIMIT_RETRIES)
+        return res;
+    console.log(`• Uploading too fast, trying again in 30 seconds`);
+    await setTimeout(RATE_LIMIT_DELAY_MS);
+    return requestUploadUrl(params, attempt + 1);
+};
+export const uploadFile = async (fileName, fileContents, contentType, type = "question-type") => {
+    const params = new URLSearchParams();
+    params.append("filename", basename(fileName));
+    params.append("contentType", contentType);
+    params.append("type", type);
+    const res = await requestUploadUrl(params);
     if (!res.ok) {
         const errorText = await res.text();
         console.error(`🚫 Upload failed: ${errorText}`);

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

@@ -0,0 +1,21 @@
+export type Uploader = (fileName: string, contents: string | Buffer, contentType: string) => Promise<string>;
+export declare const findAppFile: (dir: string) => Promise<string>;
+/** Evaluates the app module in Node, returning the definition `defineApp()` built. */
+export declare const loadAppDefinition: (file: string) => Promise<Record<string, any>>;
+/**
+ * Bundles the app for the sandbox, which only offers standard JavaScript and
+ * `fetch`: a script defining `examplaryApp`, whose default export runs a hook.
+ */
+export declare const buildServerBundle: (file: string) => Promise<{
+    js: string;
+    sourcemap: string;
+    sha256: string;
+}>;
+/** Like `uploadPath`, for a path or an object of paths by language. */
+export declare const uploadTranslatablePath: (dir: string, value: string | Record<string, string> | undefined, upload: Uploader) => Promise<any>;
+/**
+ * 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 declare const buildAppManifest: (file: string, definition: Record<string, any>, uploadFile: Uploader) => Promise<Record<string, any>>;

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;
+};