@kradle/cli 0.0.2

package/dist/commands/challenge/multi-upload.js

@@ -0,0 +1,80 @@
+import { Command } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { Challenge } from "../../lib/challenge.js";
+import { loadConfig } from "../../lib/config.js";
+export default class MultiUpload extends Command {
+    static description = "Interactively select and upload multiple challenges";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        // Not necessary since we don't have any args, but oclif will raise a warning if we don't parse the args
+        this.parse(MultiUpload);
+        const config = loadConfig();
+        const api = new ApiClient(config);
+        this.log(pc.blue(">> Loading challenges..."));
+        const [cloudChallenges, localChallenges, human] = await Promise.all([
+            api.listChallenges(),
+            Challenge.getLocalChallenges(),
+            api.getHuman(),
+        ]);
+        // Get local challenges that exist
+        const localChallengeIds = Object.keys(localChallenges);
+        if (localChallengeIds.length === 0) {
+            this.log(pc.yellow("No local challenges found"));
+            return;
+        }
+        // Create choices with status information
+        const cloudMap = new Map(cloudChallenges.map((c) => [c.slug, c]));
+        const choices = localChallengeIds.map((id) => {
+            const fullSlug = `${human.username}:${id}`;
+            const inCloud = cloudMap.has(fullSlug);
+            const status = inCloud ? pc.green("☁️ ") : pc.blue("💻");
+            return {
+                name: id,
+                message: `${status} ${id}`,
+            };
+        });
+        // Prompt user to select challenges
+        let response;
+        try {
+            response = await enquirer.prompt({
+                type: "multiselect",
+                name: "challenges",
+                message: "Select challenges to upload. ☁️ = exists in cloud, 📁 = exists locally only",
+                choices: choices.map((c) => c.message),
+            });
+        }
+        catch (error) {
+            this.log(pc.yellow(">> No challenges selected"));
+            return;
+        }
+        // Map back to challenge IDs
+        const selectedChallenges = response.challenges.map((selected) => {
+            const choice = choices.find((c) => c.message === selected);
+            return choice?.name || selected.replace(/^[✓⊡]\s+/, "");
+        });
+        // Create tasks for each challenge
+        const tasks = new Listr(selectedChallenges.map((challengeId) => ({
+            title: challengeId,
+            task: async () => {
+                const challenge = new Challenge(challengeId, config);
+                await challenge.build();
+                await challenge.upload(api);
+            },
+        })), {
+            concurrent: false,
+            exitOnError: false,
+        });
+        try {
+            await tasks.run();
+            this.log(pc.green(`\n✓ Uploaded ${selectedChallenges.length} challenges`));
+        }
+        catch (error) {
+            this.error(pc.red(`Some uploads failed: ${error instanceof Error ? error.message : String(error)}`), {
+                exit: false,
+            });
+        }
+    }
+}

package/dist/commands/challenge/run.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "@oclif/core";
+export default class Run extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        challenge: import("@oclif/core/interfaces").Arg<string>;
+    };
+    static flags: {
+        studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/run.js

@@ -0,0 +1,47 @@
+import { Command, Flags } from "@oclif/core";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge } from "../../lib/challenge.js";
+import { loadConfig } from "../../lib/config.js";
+import { loadTemplateRun } from "../../lib/utils.js";
+export default class Run extends Command {
+    static description = "Run a challenge";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --studio",
+    ];
+    static args = {
+        challenge: getChallengeSlugArgument({ description: "Challenge slug to run" }),
+    };
+    static flags = {
+        studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Run);
+        const config = loadConfig();
+        const api = new ApiClient(config);
+        const challenge = new Challenge(args.challenge, config);
+        try {
+            const { participants } = (await loadTemplateRun());
+            const template = {
+                challenge: challenge.shortSlug,
+                participants,
+            };
+            this.log(pc.blue(`>> Running challenge: ${challenge.shortSlug}${flags.studio ? " (studio)" : ""}...`));
+            const response = await api.runChallenge(template, flags.studio);
+            if (response.runIds && response.runIds.length > 0) {
+                const baseUrl = flags.studio ? config.STUDIO_URL : config.WEB_URL;
+                const runUrl = `${baseUrl}/runs/${response.runIds[0]}`;
+                this.log(pc.green("\n✓ Challenge started!"));
+                this.log(pc.dim(`Run URL: ${runUrl}`));
+            }
+            else {
+                this.log(pc.yellow("⚠ Challenge started but no run ID returned"));
+            }
+        }
+        catch (error) {
+            this.error(pc.red(`Run failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

package/dist/commands/challenge/watch.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "@oclif/core";
+export default class Watch extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static args: {
+        challenge: import("@oclif/core/interfaces").Arg<string>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/watch.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import chokidar from "chokidar";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge } from "../../lib/challenge.js";
+import { loadConfig } from "../../lib/config.js";
+import { clearScreen, debounced } from "../../lib/utils.js";
+export default class Watch extends Command {
+    static description = "Watch a challenge for changes and auto-rebuild/upload";
+    static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
+    static flags = {
+        verbose: Flags.boolean({ description: "Enable verbose output", default: false }),
+    };
+    static args = {
+        challenge: getChallengeSlugArgument({ description: "Challenge slug to watch" }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Watch);
+        const config = loadConfig();
+        const challenge = new Challenge(args.challenge, config);
+        const api = new ApiClient(config);
+        const debounceSeconds = 1;
+        let building = false;
+        // Perform the initial build and upload
+        this.log(pc.blue(`Performing initial build and upload...`));
+        let { config: lastConfig, datapackHash: lastHash } = await challenge.buildAndUpload(api);
+        this.log(pc.green(`✓ Initial build and upload complete`));
+        const executeRebuild = async () => {
+            building = true;
+            // Clear screen before subsequent rebuilds for clean output
+            clearScreen();
+            this.log(pc.cyan(`\n  Rebuild started...\n`));
+            const tasks = new Listr([
+                {
+                    title: "Checking configuration",
+                    task: async (_ctx, task) => {
+                        const newConfig = await challenge.loadConfig();
+                        if (JSON.stringify(newConfig) !== JSON.stringify(lastConfig)) {
+                            task.title = "Uploading configuration";
+                            await api.updateChallenge(challenge, newConfig);
+                            lastConfig = newConfig;
+                            task.title = "Configuration uploaded";
+                        }
+                        else {
+                            task.title = "Configuration unchanged";
+                            task.skip("No configuration changes detected");
+                        }
+                    },
+                },
+                {
+                    title: "Building datapack",
+                    task: async (_ctx, task) => {
+                        await challenge.build(!flags.verbose);
+                        task.title = "Datapack built";
+                    },
+                },
+                {
+                    title: "Checking datapack changes",
+                    task: async (_ctx, task) => {
+                        const newHash = await challenge.getDatapackHash();
+                        if (newHash !== lastHash) {
+                            task.title = "Uploading datapack";
+                            await challenge.upload(api);
+                            lastHash = newHash;
+                            task.title = "Datapack uploaded";
+                        }
+                        else {
+                            task.title = "Datapack unchanged";
+                            task.skip("No datapack changes detected");
+                        }
+                    },
+                },
+            ], {
+                renderer: flags.verbose ? "verbose" : "default",
+            });
+            try {
+                await tasks.run();
+                this.log(pc.green(`\n✓ Rebuild complete`));
+            }
+            catch (error) {
+                this.log(pc.red(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`));
+            }
+            this.log(pc.dim("Watching for changes... (Ctrl+C to stop)\n"));
+            building = false;
+        };
+        const debouncedBuild = debounced(() => executeRebuild(), debounceSeconds * 1000);
+        this.log(pc.blue(`\nStarting watch mode for ${pc.bold(challenge.shortSlug)}\n`));
+        this.log(pc.dim("Watching for changes... (Ctrl+C to stop)\n"));
+        const watcher = chokidar.watch([challenge.challengeDir], {
+            ignored: /(^|[/\\])\../, // ignore dotfiles
+            persistent: true,
+            ignoreInitial: true,
+        });
+        watcher
+            .on("change", (filePath) => {
+            if (building)
+                return;
+            this.log(pc.cyan(`  → File changed: ${pc.bold(path.basename(filePath))}`));
+            debouncedBuild();
+        })
+            .on("add", (filePath) => {
+            if (building)
+                return;
+            this.log(pc.cyan(`  → File added: ${pc.bold(path.basename(filePath))}`));
+            debouncedBuild();
+        });
+        // Keep process alive indefinitely
+        await new Promise(() => { });
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "@oclif/core";
+export default class Init extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dev: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/init.js

@@ -0,0 +1,161 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { executeCommand, getStaticResourcePath, readDirSorted } from "../lib/utils.js";
+export default class Init extends Command {
+    static description = "Initialize a new Kradle project. If the current directory is not empty, it will create a subdirectory for the project. Else, the current directory will be used.";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    static flags = {
+        name: Flags.string({
+            char: "n",
+            description: "Project name",
+            required: false,
+        }),
+        dev: Flags.boolean({
+            char: "d",
+            description: "Use Kradle's development environment instead of production",
+            required: false,
+        }),
+        "api-key": Flags.string({
+            char: "k",
+            description: "Kradle API key",
+            required: false,
+        }),
+    };
+    async run() {
+        try {
+            // Check if current directory is empty
+            const cwd = process.cwd();
+            const files = await fs.readdir(cwd);
+            const { flags } = await this.parse(Init);
+            const nonHiddenFiles = files.filter((f) => !f.startsWith("."));
+            const useCurrentDir = nonHiddenFiles.length === 0;
+            if (useCurrentDir) {
+                this.log(pc.yellow("Current directory is empty, it will be used as the project directory."));
+            }
+            else {
+                this.log(pc.yellow("Current directory is not empty, a subdirectory will be created for the project."));
+            }
+            let projectName;
+            if (flags.name) {
+                projectName = flags.name;
+            }
+            else {
+                let initial;
+                if (useCurrentDir) {
+                    initial = path.basename(cwd);
+                }
+                const { name } = await enquirer.prompt({
+                    type: "input",
+                    name: "name",
+                    message: "Enter the project name:",
+                    initial: initial,
+                });
+                projectName = name;
+            }
+            let useDev = flags.dev;
+            if (!useDev) {
+                const { confirm } = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: "Do you want to use Kradle's development environment?",
+                    initial: false,
+                });
+                useDev = confirm;
+            }
+            if (useDev) {
+                this.log(pc.yellow("Using Kradle's development environment."));
+            }
+            else {
+                this.log(pc.green("Using Kradle's production environment."));
+            }
+            const domain = useDev ? "dev.kradle.ai" : "kradle.ai";
+            let apiKey;
+            if (flags["api-key"]) {
+                apiKey = flags["api-key"];
+            }
+            else {
+                this.log(pc.dim(`\nGet your API key at: https://${domain}/settings#api-keys`));
+                const { key } = await enquirer.prompt({
+                    type: "password",
+                    name: "key",
+                    message: "Enter your Kradle API key:",
+                    required: true,
+                });
+                apiKey = key;
+            }
+            const targetDir = useCurrentDir ? cwd : path.join(cwd, projectName);
+            const tasks = new Listr([
+                {
+                    title: "Creating project directory",
+                    skip: () => useCurrentDir,
+                    task: async () => {
+                        await fs.mkdir(targetDir, { recursive: true });
+                    },
+                },
+                {
+                    title: "Copying template files",
+                    task: async () => {
+                        const templateDir = getStaticResourcePath("project_template");
+                        const templateFiles = await readDirSorted(templateDir);
+                        for (const file of templateFiles) {
+                            if (file.name.endsWith(".env")) {
+                                // We ignore .env as it will be created later
+                                continue;
+                            }
+                            const srcPath = path.join(file.parentPath, file.name);
+                            const srcRelativePath = path.relative(templateDir, srcPath);
+                            const destPath = path.join(targetDir, srcRelativePath);
+                            await fs.copyFile(srcPath, destPath);
+                        }
+                        // Create .env file based on the environment
+                        const sourceEnvPath = useDev ? path.join(templateDir, "dev.env") : path.join(templateDir, "prod.env");
+                        const destEnvPath = path.join(targetDir, ".env");
+                        const sourceEnvContent = await fs.readFile(sourceEnvPath, "utf-8");
+                        const updatedEnvContent = `${sourceEnvContent}\nKRADLE_API_KEY=${apiKey}`;
+                        await fs.writeFile(destEnvPath, updatedEnvContent);
+                    },
+                },
+                {
+                    title: "Updating package.json",
+                    task: async () => {
+                        await executeCommand("npm", ["pkg", "set", `name=${projectName}`, `description=${projectName} challenges`], {
+                            cwd: targetDir,
+                        });
+                    },
+                },
+                {
+                    title: "Installing dependencies",
+                    task: async (_) => {
+                        try {
+                            await executeCommand("npm", ["install"], {
+                                cwd: targetDir,
+                            });
+                        }
+                        catch (error) {
+                            throw new Error(pc.red(`Failed to install dependencies: ${error instanceof Error ? error.message : String(error)}`));
+                        }
+                    },
+                },
+            ]);
+            await tasks.run();
+            // Display success message and next steps
+            this.log(pc.green(`\n✓ Project initialized successfully!`));
+            this.log(pc.dim(`\nProject location: ${targetDir}`));
+            this.log(pc.bold("\n📝 Next steps:"));
+            if (targetDir !== cwd) {
+                this.log(pc.cyan(`  cd ${projectName}`));
+            }
+            this.log(pc.cyan(`  Create your first challenge: "kradle challenge create <challenge-name>"
+
+💡 Tip: Enable shell autocomplete with "kradle autocomplete"
+`));
+        }
+        catch (error) {
+            this.error(pc.red(`Init failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from "@oclif/core";

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from "@oclif/core";

package/dist/lib/api-client.d.ts

@@ -0,0 +1,55 @@
+import type z from "zod";
+import type { Challenge } from "./challenge.js";
+import type { Config } from "./config.js";
+import { type AgentSchemaType, type ChallengeSchemaType, HumanSchema } from "./schemas.js";
+export declare class ApiClient {
+    private config;
+    constructor(config: Config);
+    private request;
+    private get;
+    private post;
+    private put;
+    private delete;
+    /**
+     * List a resource from the API.
+     * @param url - The URL to list the resource from.
+     * @param property - The property of the response that contains the resources.
+     * @param schema - The schema to parse the response.
+     * @param pageSize - The number of resources to list per page.
+     * @returns The resources.
+     *
+     * @example
+     * // The "list_challenges" API returns a response like:
+     * // { challenges: [...], nextPageToken: string }
+     *
+     * const challenges = await this.listResource("list_challenges", "challenges", ChallengesResponseSchema);
+     * console.log(challenges);
+     */
+    private listResource;
+    getHuman(): Promise<z.infer<typeof HumanSchema>>;
+    listChallenges(): Promise<ChallengeSchemaType[]>;
+    listKradleAgents(): Promise<AgentSchemaType[]>;
+    getChallenge(challengeId: string): Promise<ChallengeSchemaType>;
+    /**
+     * Check if a challenge exists in the cloud.
+     * @param slug - The slug of the challenge.
+     * @returns True if the challenge exists, false otherwise.
+     */
+    challengeExists(slug: string): Promise<boolean>;
+    createChallenge(slug: string): Promise<unknown>;
+    /**
+     * Update a challenge definition in the cloud.
+     * @param challenge - The challenge to update.
+     * @param challengeConfig - The challenge config to upload. If not provided, the config will be loaded from the challenge.
+     * @returns The updated challenge.
+     */
+    updateChallenge(challenge: Challenge, challengeConfig?: ChallengeSchemaType): Promise<void>;
+    getChallengeUploadUrl(challenge: Challenge): Promise<string>;
+    runChallenge(runData: {
+        challenge: string;
+        participants: unknown[];
+    }, studio?: boolean): Promise<{
+        runIds?: string[] | undefined;
+    }>;
+    deleteChallenge(challengeId: string): Promise<void>;
+}

package/dist/lib/api-client.js

@@ -0,0 +1,162 @@
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, HumanSchema, RunResponseSchema, UploadUrlResponseSchema, } from "./schemas.js";
+const DEFAULT_PAGE_SIZE = 30;
+const DEFAULT_CHALLENGE_SCHEMA = {
+    slug: "",
+    name: "",
+    visibility: "private",
+    domain: "minecraft",
+    world: "team-kradle:colosseum",
+    challengeConfig: { cheat: false, datapack: true, gameMode: "survival" },
+    task: ".",
+    roles: { "default-role": { description: "default-role", specificTask: "do your best!" } },
+    objective: {
+        fieldName: "success_rate",
+        direction: "maximize",
+    },
+};
+export class ApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(target, url, options) {
+        const baseUrl = target === "web" ? this.config.WEB_API_URL : this.config.STUDIO_API_URL;
+        const fullUrl = `${baseUrl}/${url}`;
+        const response = await fetch(fullUrl, {
+            ...options,
+            headers: {
+                Authorization: `Bearer ${this.config.KRADLE_API_KEY}`,
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`API call failed: ${url} - ${response.status} ${response.statusText}\n${text}`);
+        }
+        return response;
+    }
+    async get(target, url, options = {}, schema) {
+        const response = await this.request(target, url, {
+            method: "GET",
+            ...options,
+        });
+        const data = await response.json();
+        return schema ? schema.parse(data) : data;
+    }
+    async post(target, url, options = {}, schema) {
+        const response = await this.request(target, url, {
+            method: "POST",
+            ...options,
+        });
+        const data = await response.json();
+        return schema ? schema.parse(data) : data;
+    }
+    async put(target, url, options = {}) {
+        await this.request(target, url, {
+            method: "PUT",
+            ...options,
+        });
+    }
+    async delete(target, url, options = {}) {
+        await this.request(target, url, {
+            method: "DELETE",
+            ...options,
+        });
+    }
+    /**
+     * List a resource from the API.
+     * @param url - The URL to list the resource from.
+     * @param property - The property of the response that contains the resources.
+     * @param schema - The schema to parse the response.
+     * @param pageSize - The number of resources to list per page.
+     * @returns The resources.
+     *
+     * @example
+     * // The "list_challenges" API returns a response like:
+     * // { challenges: [...], nextPageToken: string }
+     *
+     * const challenges = await this.listResource("list_challenges", "challenges", ChallengesResponseSchema);
+     * console.log(challenges);
+     */
+    async listResource(url, property, schema, pageSize = DEFAULT_PAGE_SIZE) {
+        let pageToken;
+        const resources = [];
+        do {
+            const params = new URLSearchParams();
+            if (pageToken)
+                params.set("page_token", pageToken);
+            params.set("page_size", String(pageSize));
+            const response = await this.get("web", `${url}?${params}`, {
+                headers: {
+                    "Content-Type": "application/json",
+                },
+            }, schema);
+            resources.push(...response[property]);
+            pageToken = response?.nextPageToken;
+        } while (pageToken);
+        return resources;
+    }
+    async getHuman() {
+        const url = "human";
+        return this.get("web", url, {}, HumanSchema);
+    }
+    async listChallenges() {
+        return this.listResource("challenges", "challenges", ChallengesResponseSchema);
+    }
+    async listKradleAgents() {
+        return this.listResource("humans/team-kradle/agents", "agents", AgentsResponseSchema);
+    }
+    async getChallenge(challengeId) {
+        const url = `challenges/${challengeId}`;
+        return this.get("web", url, {}, ChallengeSchema);
+    }
+    /**
+     * Check if a challenge exists in the cloud.
+     * @param slug - The slug of the challenge.
+     * @returns True if the challenge exists, false otherwise.
+     */
+    async challengeExists(slug) {
+        try {
+            await this.getChallenge(slug);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    async createChallenge(slug) {
+        const challenge = { ...DEFAULT_CHALLENGE_SCHEMA, slug: slug, name: slug };
+        const url = "challenges";
+        return this.post("web", url, {
+            body: JSON.stringify(challenge),
+        });
+    }
+    /**
+     * Update a challenge definition in the cloud.
+     * @param challenge - The challenge to update.
+     * @param challengeConfig - The challenge config to upload. If not provided, the config will be loaded from the challenge.
+     * @returns The updated challenge.
+     */
+    async updateChallenge(challenge, challengeConfig) {
+        const url = `challenges/${challenge.shortSlug}`;
+        const config = challengeConfig ?? (await challenge.loadConfig());
+        return this.put("web", url, {
+            body: JSON.stringify(config),
+        });
+    }
+    async getChallengeUploadUrl(challenge) {
+        const response = await this.get("web", `challenges/${challenge.shortSlug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
+        return response.uploadUrl;
+    }
+    async runChallenge(runData, studio = false) {
+        const url = "jobs";
+        return this.post(studio ? "studio" : "web", url, {
+            body: JSON.stringify(runData),
+        }, RunResponseSchema);
+    }
+    async deleteChallenge(challengeId) {
+        const url = `challenges/${challengeId}`;
+        await this.delete("web", url);
+    }
+}

package/dist/lib/arguments.d.ts

@@ -0,0 +1,7 @@
+import type { Arg } from "@oclif/core/interfaces";
+/**
+ * Returns a "challenge slug" argument, and validates it to be a valid challenge slug.
+ */
+export declare function getChallengeSlugArgument({ description }: {
+    description: string;
+}): Arg<string>;