@kradle/cli 0.0.2

package/dist/lib/arguments.js

@@ -0,0 +1,17 @@
+import { Args } from "@oclif/core";
+const CHALLENGE_SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Returns a "challenge slug" argument, and validates it to be a valid challenge slug.
+ */
+export function getChallengeSlugArgument({ description }) {
+    return Args.string({
+        description,
+        required: true,
+        parse: async (input) => {
+            if (!CHALLENGE_SLUG_REGEX.test(input)) {
+                throw new Error(`Invalid challenge slug: ${input}. Challenge slugs must be lowercase alphanumeric characters and hyphens, and must not start or end with a hyphen.`);
+            }
+            return input;
+        },
+    });
+}

package/dist/lib/challenge.d.ts

@@ -0,0 +1,67 @@
+import type { ApiClient } from "./api-client.js";
+import type { Config } from "./config.js";
+import { type ChallengeSchemaType } from "./schemas.js";
+export declare class Challenge {
+    readonly name: string;
+    private readonly config;
+    constructor(name: string, config: Config);
+    private get kradleChallengesPath();
+    /**
+     * Get the short slug without username prefix
+     * e.g., "florianernst:challenge" -> "challenge"
+     */
+    get shortSlug(): string;
+    /**
+     * Get the path to the challenge directory
+     */
+    get challengeDir(): string;
+    /**
+     * Get the path to the challenge TypeScript entrypoint file
+     */
+    get challengePath(): string;
+    /**
+     * Get the path to the challenge config file
+     */
+    get configPath(): string;
+    /**
+     * Get the path to the datapack directory
+     */
+    get datapackPath(): string;
+    /**
+     * Get the path to the tarball file
+     */
+    get tarballPath(): string;
+    /**
+     * Make sure the challenge exists locally and is valid by ensuring the challenge.ts file and the config.ts file exist.
+     */
+    exists(): boolean;
+    /**
+     * Calculate a SHA256 hash of all files in the datapack directory
+     */
+    getDatapackHash(): Promise<string>;
+    /**
+     * Build the challenge datapack
+     */
+    build(silent?: boolean): Promise<void>;
+    /**
+     * Load the challenge configuration from config.ts
+     */
+    loadConfig(): Promise<ChallengeSchemaType>;
+    /**
+     * Upload the challenge datapack to Google Cloud Storage
+     */
+    upload(apiClient: ApiClient): Promise<void>;
+    buildAndUpload(api: ApiClient): Promise<{
+        config: ChallengeSchemaType;
+        datapackHash: string;
+    }>;
+    /**
+     * Get all local challenges from the challenges directory
+     */
+    static getLocalChallenges(): Promise<Record<string, boolean>>;
+    /**
+     * Create a new local challenge folder with challenge.ts template
+     * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
+     */
+    static createLocal(slug: string, config: Config): Promise<void>;
+}

package/dist/lib/challenge.js

@@ -0,0 +1,203 @@
+import crypto from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+import * as tar from "tar";
+import { ChallengeSchema } from "./schemas.js";
+import { executeNodeCommand, executeTypescriptFile, getStaticResourcePath, readDirSorted } from "./utils.js";
+export class Challenge {
+    name;
+    config;
+    constructor(name, config) {
+        this.name = name;
+        this.config = config;
+    }
+    get kradleChallengesPath() {
+        return path.resolve(this.config.KRADLE_CHALLENGES_PATH);
+    }
+    /**
+     * Get the short slug without username prefix
+     * e.g., "florianernst:challenge" -> "challenge"
+     */
+    get shortSlug() {
+        return this.name.includes(":") ? this.name.split(":")[1] : this.name;
+    }
+    /**
+     * Get the path to the challenge directory
+     */
+    get challengeDir() {
+        return path.resolve(process.cwd(), "challenges", this.shortSlug);
+    }
+    /**
+     * Get the path to the challenge TypeScript entrypoint file
+     */
+    get challengePath() {
+        return path.join(this.challengeDir, "challenge.ts");
+    }
+    /**
+     * Get the path to the challenge config file
+     */
+    get configPath() {
+        return path.join(this.challengeDir, "config.ts");
+    }
+    /**
+     * Get the path to the datapack directory
+     */
+    get datapackPath() {
+        return path.join(this.kradleChallengesPath, this.shortSlug);
+    }
+    /**
+     * Get the path to the tarball file
+     */
+    get tarballPath() {
+        return path.join(this.kradleChallengesPath, `${this.shortSlug}.tar.gz`);
+    }
+    /**
+     * Make sure the challenge exists locally and is valid by ensuring the challenge.ts file and the config.ts file exist.
+     */
+    exists() {
+        if (!existsSync(this.challengePath)) {
+            return false;
+        }
+        if (!existsSync(this.configPath)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Calculate a SHA256 hash of all files in the datapack directory
+     */
+    async getDatapackHash() {
+        const datapackDir = path.join(this.datapackPath, "datapack");
+        if (!existsSync(datapackDir)) {
+            throw new Error(`Datapack not found at ${datapackDir}`);
+        }
+        const files = await readDirSorted(datapackDir);
+        const hash = crypto.createHash("sha256");
+        for (const file of files) {
+            if (file.isFile()) {
+                const filePath = path.join(file.parentPath, file.name);
+                const content = await fs.readFile(filePath);
+                hash.update(content);
+            }
+        }
+        return hash.digest("hex");
+    }
+    /**
+     * Build the challenge datapack
+     */
+    async build(silent = false) {
+        // Verify that the challenge file exists
+        if (!existsSync(this.challengePath)) {
+            throw new Error(`Challenge file not found at ${this.challengePath}`);
+        }
+        try {
+            await executeTypescriptFile(this.challengePath, this.config, { silent });
+        }
+        catch (error) {
+            throw new Error(`Failed to build datapack: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    /**
+     * Load the challenge configuration from config.ts
+     */
+    async loadConfig() {
+        if (!existsSync(this.configPath)) {
+            throw new Error(`Config file not found at ${this.configPath}`);
+        }
+        // We spawn a new NodeJS process to execute & log the config file.
+        // We can't directly import the file because it would be cached, and import cache can't be invalidated.
+        const stdout = await executeNodeCommand([
+            "--experimental-transform-types",
+            "--no-warnings",
+            "-e",
+            `console.log(JSON.stringify(require("${this.configPath}").config));`,
+        ], this.config);
+        return ChallengeSchema.parse(JSON.parse(stdout));
+    }
+    /**
+     * Upload the challenge datapack to Google Cloud Storage
+     */
+    async upload(apiClient) {
+        // Create tarball
+        // We need to use the cwd option to make sure the structure of the tarball uses paths relative to the challenge directory
+        await tar.create({
+            "no-mtime": true,
+            file: this.tarballPath, // Output file name
+            gzip: true,
+            cwd: this.datapackPath, // Input directory
+            strict: true,
+        }, ["datapack"]);
+        const uploadUrl = await apiClient.getChallengeUploadUrl(this);
+        const fileBuffer = await fs.readFile(this.tarballPath);
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/gzip",
+                "Content-Length": fileBuffer.length.toString(),
+            },
+            body: fileBuffer,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to upload datapack: ${response.statusText}`);
+        }
+    }
+    async buildAndUpload(api) {
+        // Ensure challenge exists locally
+        if (!this.exists()) {
+            throw new Error(`Challenge "${this.name}" does not exist locally. Make sure both the challenge.ts file and the config.ts file exist.`);
+        }
+        // Ensure challenge exists in the cloud
+        if (!(await api.challengeExists(this.name))) {
+            console.log(pc.yellow(`Challenge not found in cloud: ${this.name}`));
+            console.log(pc.yellow(`Creating challenge: ${this.name}`));
+            await api.createChallenge(this.name);
+            console.log(pc.green(`✓ Challenge created in cloud`));
+        }
+        // Load config
+        const config = await this.loadConfig();
+        // Upload config
+        console.log(pc.blue(`>> Uploading config: ${this.shortSlug}`));
+        await api.updateChallenge(this, config);
+        console.log(pc.green(`✓ Config uploaded`));
+        // Build and upload datapack
+        console.log(pc.blue(`>> Building datapack: ${this.shortSlug}`));
+        await this.build();
+        console.log(pc.blue(`>> Uploading datapack: ${this.shortSlug}`));
+        await this.upload(api);
+        console.log(pc.green(`✓ Build & upload complete for ${this.shortSlug}`));
+        const datapackHash = await this.getDatapackHash();
+        return { config, datapackHash };
+    }
+    /**
+     * Get all local challenges from the challenges directory
+     */
+    static async getLocalChallenges() {
+        const challengesDir = path.resolve(process.cwd(), "challenges");
+        const entries = await readDirSorted(challengesDir);
+        const challenges = {};
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                // Check if it has a challenge.ts file
+                const challengePath = path.join(challengesDir, entry.name, "challenge.ts");
+                if (existsSync(challengePath)) {
+                    challenges[entry.name] = true;
+                }
+            }
+        }
+        return challenges;
+    }
+    /**
+     * Create a new local challenge folder with challenge.ts template
+     * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
+     */
+    static async createLocal(slug, config) {
+        const challenge = new Challenge(slug, config);
+        const challengeTemplatePath = getStaticResourcePath("challenge.ts");
+        // Create challenge directory
+        await fs.mkdir(challenge.challengeDir, { recursive: true });
+        // Copy challenge.ts template
+        await fs.copyFile(challengeTemplatePath, challenge.challengePath);
+    }
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const ConfigSchema: z.ZodObject<{
+    WEB_API_URL: z.ZodString;
+    WEB_URL: z.ZodString;
+    STUDIO_API_URL: z.ZodString;
+    STUDIO_URL: z.ZodString;
+    KRADLE_API_KEY: z.ZodString;
+    GCS_BUCKET: z.ZodString;
+    KRADLE_CHALLENGES_PATH: z.ZodDefault<z.ZodString>;
+    NAMESPACE: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;

package/dist/lib/config.js

@@ -0,0 +1,51 @@
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { untildify } from "./utils.js";
+export const ConfigSchema = z.object({
+    WEB_API_URL: z.string().url(),
+    WEB_URL: z.string().url(),
+    STUDIO_API_URL: z.string().url(),
+    STUDIO_URL: z.string(),
+    KRADLE_API_KEY: z.string(),
+    GCS_BUCKET: z.string(),
+    /**
+     * Absolute path to the challenges directory. Defaults to ~/Documents/kradle-studio/challenges.
+     */
+    KRADLE_CHALLENGES_PATH: z.string().default(path.join(os.homedir(), "Documents", "kradle-studio", "challenges")),
+    NAMESPACE: z.string().default("kradle"),
+});
+export function loadConfig() {
+    try {
+        /**
+         * First, resolve tildes in the KRADLE_CHALLENGES_PATH
+         */
+        let challengesPath;
+        if (process.env.KRADLE_CHALLENGES_PATH) {
+            challengesPath = untildify(process.env.KRADLE_CHALLENGES_PATH);
+        }
+        const config = ConfigSchema.parse({
+            WEB_API_URL: process.env.WEB_API_URL,
+            WEB_URL: process.env.WEB_URL,
+            STUDIO_API_URL: process.env.STUDIO_API_URL,
+            STUDIO_URL: process.env.STUDIO_URL,
+            KRADLE_API_KEY: process.env.KRADLE_API_KEY,
+            GCS_BUCKET: process.env.GCS_BUCKET,
+            KRADLE_CHALLENGES_PATH: challengesPath,
+            NAMESPACE: process.env.NAMESPACE,
+        });
+        for (const field of Object.keys(config)) {
+            if (!config[field]) {
+                throw new Error(`Missing required config field: "${field}". Please check your .env file.`);
+            }
+        }
+        return config;
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const missingFields = error.issues.map((e) => e.path.join(".")).join(", ");
+            throw new Error(`Missing or invalid environment variables: ${missingFields}. Please check your .env file.`);
+        }
+        throw error;
+    }
+}

package/dist/lib/schemas.d.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+export declare const ChallengeSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    slug: z.ZodString;
+    name: z.ZodString;
+    visibility: z.ZodEnum<{
+        private: "private";
+        public: "public";
+        unlisted: "unlisted";
+    }>;
+    domain: z.ZodString;
+    world: z.ZodString;
+    challengeConfig: z.ZodObject<{
+        cheat: z.ZodBoolean;
+        datapack: z.ZodBoolean;
+        gameMode: z.ZodEnum<{
+            survival: "survival";
+            creative: "creative";
+            adventure: "adventure";
+            spectator: "spectator";
+        }>;
+    }, z.core.$strip>;
+    task: z.ZodString;
+    roles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        specificTask: z.ZodString;
+    }, z.core.$strip>>;
+    objective: z.ZodObject<{
+        fieldName: z.ZodString;
+        direction: z.ZodEnum<{
+            maximize: "maximize";
+            minimize: "minimize";
+        }>;
+    }, z.core.$strip>;
+    creationTime: z.ZodOptional<z.ZodString>;
+    updateTime: z.ZodOptional<z.ZodString>;
+    creator: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ChallengesResponseSchema: z.ZodObject<{
+    challenges: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        slug: z.ZodString;
+        name: z.ZodString;
+        visibility: z.ZodEnum<{
+            private: "private";
+            public: "public";
+            unlisted: "unlisted";
+        }>;
+        domain: z.ZodString;
+        world: z.ZodString;
+        challengeConfig: z.ZodObject<{
+            cheat: z.ZodBoolean;
+            datapack: z.ZodBoolean;
+            gameMode: z.ZodEnum<{
+                survival: "survival";
+                creative: "creative";
+                adventure: "adventure";
+                spectator: "spectator";
+            }>;
+        }, z.core.$strip>;
+        task: z.ZodString;
+        roles: z.ZodRecord<z.ZodString, z.ZodObject<{
+            description: z.ZodString;
+            specificTask: z.ZodString;
+        }, z.core.$strip>>;
+        objective: z.ZodObject<{
+            fieldName: z.ZodString;
+            direction: z.ZodEnum<{
+                maximize: "maximize";
+                minimize: "minimize";
+            }>;
+        }, z.core.$strip>;
+        creationTime: z.ZodOptional<z.ZodString>;
+        updateTime: z.ZodOptional<z.ZodString>;
+        creator: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const HumanSchema: z.ZodObject<{
+    username: z.ZodString;
+}, z.core.$strip>;
+export declare const RunResponseSchema: z.ZodObject<{
+    runIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const UploadUrlResponseSchema: z.ZodObject<{
+    uploadUrl: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentSchema: z.ZodObject<{
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        public: "public";
+        unlisted: "unlisted";
+    }>>;
+    creationTime: z.ZodOptional<z.ZodString>;
+    updateTime: z.ZodOptional<z.ZodString>;
+    deletionTime: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    originalCreatorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AgentsResponseSchema: z.ZodObject<{
+    agents: z.ZodArray<z.ZodObject<{
+        username: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        visibility: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            public: "public";
+            unlisted: "unlisted";
+        }>>;
+        creationTime: z.ZodOptional<z.ZodString>;
+        updateTime: z.ZodOptional<z.ZodString>;
+        deletionTime: z.ZodOptional<z.ZodString>;
+        creatorId: z.ZodOptional<z.ZodString>;
+        originalCreatorId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChallengeSchemaType = z.infer<typeof ChallengeSchema>;
+export type ChallengesResponseType = z.infer<typeof ChallengesResponseSchema>;
+export type HumanSchemaType = z.infer<typeof HumanSchema>;
+export type RunResponseType = z.infer<typeof RunResponseSchema>;
+export type AgentSchemaType = z.infer<typeof AgentSchema>;
+export type AgentsResponseType = z.infer<typeof AgentsResponseSchema>;

package/dist/lib/schemas.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+export const ChallengeSchema = z.object({
+    id: z.string().optional(),
+    slug: z.string(),
+    name: z.string(),
+    visibility: z.enum(["private", "public", "unlisted"]),
+    domain: z.string(),
+    world: z.string(),
+    challengeConfig: z.object({
+        cheat: z.boolean(),
+        datapack: z.boolean(),
+        gameMode: z.enum(["survival", "creative", "adventure", "spectator"]),
+    }),
+    task: z.string(),
+    roles: z.record(z.string(), z.object({
+        description: z.string(),
+        specificTask: z.string(),
+    })),
+    objective: z.object({
+        fieldName: z.string(),
+        direction: z.enum(["maximize", "minimize"]),
+    }),
+    creationTime: z.string().optional(),
+    updateTime: z.string().optional(),
+    creator: z.string().optional(),
+});
+export const ChallengesResponseSchema = z.object({
+    challenges: z.array(ChallengeSchema),
+    nextPageToken: z.string().optional(),
+});
+export const HumanSchema = z.object({
+    username: z.string(),
+});
+export const RunResponseSchema = z.object({
+    runIds: z.array(z.string()).optional(),
+});
+export const UploadUrlResponseSchema = z.object({
+    uploadUrl: z.string(),
+    expiresAt: z.string(),
+});
+export const AgentSchema = z.object({
+    username: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    visibility: z.enum(["private", "public", "unlisted"]).optional(),
+    creationTime: z.string().optional(),
+    updateTime: z.string().optional(),
+    deletionTime: z.string().optional(),
+    creatorId: z.string().optional(),
+    originalCreatorId: z.string().optional(),
+});
+export const AgentsResponseSchema = z.object({
+    agents: z.array(AgentSchema),
+    nextPageToken: z.string().optional(),
+});

package/dist/lib/utils.d.ts

@@ -0,0 +1,89 @@
+import type { Dirent } from "node:fs";
+import type { Config } from "./config.js";
+export declare function loadTemplateRun(): Promise<Record<string, unknown>>;
+/**
+ * Resolve tildes in a path to the home directory
+ */
+export declare function untildify(filePath: string): string;
+/**
+ * Returns a debounced function that will only be called after the delay has passed since the last call.
+ *
+ * @param fn The function to debounce.
+ * @param delay The delay in milliseconds.
+ * @returns A debounced function.
+ */
+export declare function debounced(fn: () => Promise<unknown>, delay: number): () => void;
+/**
+ * Clear the screen.
+ *
+ * @see https://stackoverflow.com/a/26373971
+ */
+export declare function clearScreen(): void;
+/**
+ * Get the path to a static resource (located in the `static` folder).
+ *
+ * @param name The name of the resource.
+ * @returns The absolute path to the resource.
+ */
+export declare function getStaticResourcePath(name: string): string;
+/**
+ * Reads a directory and returns a sorted list of files, with their types.
+ * @param dir The directory to read.
+ * @returns A sorted list of files, with their types (Dirent).
+ */
+export declare function readDirSorted(dir: string): Promise<Dirent[]>;
+/**
+ * Runs a NodeJS module. The module is executed in the current working directory, and the environment is set to the given config.
+ * stdout & stdout are piped to the parent process.
+ *
+ * Returns a promise that resolves when the module completes.
+ *
+ * @param file The file to execute.
+ * @param config The configuration to use.
+ * @param options The options to use.
+ * @param options.silent Whether to suppress stdout.
+ * @returns A promise that resolves when the command completes.
+ */
+export declare function runNodeModule(file: string, config: Config, options?: {
+    silent?: boolean;
+}): Promise<undefined>;
+/**
+ * Execute a TypeScript file using NodeJS's built-in TS support.
+ *
+ * @param filePath The path to the TypeScript file.
+ * @param config The configuration to use.
+ * @param options The options to use.
+ * @param options.silent Whether to suppress stdout.
+ * @returns The result of the execution.
+ */
+export declare function executeTypescriptFile(filePath: string, config: Config, options?: {
+    silent?: boolean;
+}): Promise<unknown>;
+/**
+ * Executes an arbitrary command. The command is spawned in the current working directory, and the environment is set to the given config.
+ *
+ * stdout will be returned as a string.
+ * if stderr is not empty, an error will be thrown.
+ *
+ * @param args The arguments to pass to the command.
+ * @param options The options to use.
+ * @param options.env The environment variables to set.
+ * @param options.cwd The current working directory.
+ * @returns A promise that resolves with the stdout of the command.
+ */
+export declare function executeCommand(command: string, args: string[], options?: {
+    env?: Record<string, string>;
+    cwd?: string;
+}): Promise<string>;
+/**
+ * Executes an arbitrary NodeJS command. The command is spawned in the current working directory, and the environment is set to the given config.
+ * It will use the process.execPath of the current process to find the NodeJS executable.
+ *
+ * stdout will be returned as a string.
+ * if stderr is not empty, an error will be thrown.
+ *
+ * @param args The arguments to pass to the command.
+ * @param config The configuration to use.
+ * @returns A promise that resolves with the stdout of the command.
+ */
+export declare function executeNodeCommand(args: string[], config: Config): Promise<string>;