@examplary/cli 1.15.0 → 1.17.0

package/README.md

@@ -1,40 +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.
-
-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
+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>>;