@kradle/cli 0.0.2

package/dist/lib/utils.js

@@ -0,0 +1,170 @@
+import { fork, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export async function loadTemplateRun() {
+    const templatePath = path.resolve(process.cwd(), "template-run.json");
+    const content = await fs.readFile(templatePath, "utf-8");
+    return JSON.parse(content);
+}
+/**
+ * Resolve tildes in a path to the home directory
+ */
+export function untildify(filePath) {
+    if (filePath.startsWith("~/")) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+}
+/**
+ * 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 function debounced(fn, delay) {
+    let timeoutId = null;
+    return () => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => fn(), delay);
+    };
+}
+/**
+ * Clear the screen.
+ *
+ * @see https://stackoverflow.com/a/26373971
+ */
+export function clearScreen() {
+    process.stdout.write("\x1Bc");
+}
+/**
+ * Returns the directory name of the current module.
+ *
+ * @returns The directory name of the current module.
+ */
+function getDirName() {
+    // In NodeJS, __dirname is the directory of the current module - but if we use ESM, __dirname is undefined and we should
+    // instead use the import.meta.url to get the directory of the current module.
+    try {
+        return __dirname;
+    }
+    catch {
+        return path.dirname(fileURLToPath(import.meta.url));
+    }
+}
+/**
+ * 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 function getStaticResourcePath(name) {
+    return path.resolve(getDirName(), "..", "..", "static", name);
+}
+/**
+ * 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 async function readDirSorted(dir) {
+    const files = await fs.readdir(dir, { recursive: true, withFileTypes: true });
+    return files.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * 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 function runNodeModule(file, config, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = fork(file, {
+            cwd: path.resolve(process.cwd()),
+            env: { ...process.env, ...config },
+            silent: options.silent,
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`Command failed with code ${code}`));
+            }
+            resolve(undefined);
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+/**
+ * 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 async function executeTypescriptFile(filePath, config, options = {}) {
+    return await runNodeModule(filePath, config, options);
+}
+/**
+ * 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 async function executeCommand(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: path.resolve(options?.cwd ?? process.cwd()),
+            env: { ...process.env, ...(options?.env ?? {}) },
+        });
+        // Accumulate stdout and stderr
+        let stdout = "";
+        child.stdout?.on("data", (data) => {
+            stdout += data;
+        });
+        let stderr = "";
+        child.stderr?.on("data", (data) => {
+            stderr += data;
+        });
+        child.on("close", (code) => {
+            if (code !== 0 || stderr.length > 0) {
+                reject(new Error(`Command failed with code ${code} and stderr: ${stderr}`));
+            }
+            resolve(stdout);
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+/**
+ * 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 async function executeNodeCommand(args, config) {
+    return executeCommand(process.execPath, args, { env: config });
+}

package/oclif.manifest.json

@@ -0,0 +1,310 @@
+{
+  "commands": {
+    "init": {
+      "aliases": [],
+      "args": {},
+      "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.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "name": {
+          "char": "n",
+          "description": "Project name",
+          "name": "name",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dev": {
+          "char": "d",
+          "description": "Use Kradle's development environment instead of production",
+          "name": "dev",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "api-key": {
+          "char": "k",
+          "description": "Kradle API key",
+          "name": "api-key",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init.js"
+      ]
+    },
+    "agent:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List all agents",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:list",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "agent",
+        "list.js"
+      ]
+    },
+    "challenge:build": {
+      "aliases": [],
+      "args": {
+        "challenge": {
+          "description": "Challenge slug to build",
+          "name": "challenge",
+          "required": true
+        }
+      },
+      "description": "Build and upload challenge datapack and config",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-challenge"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:build",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "build.js"
+      ]
+    },
+    "challenge:create": {
+      "aliases": [],
+      "args": {
+        "challenge": {
+          "description": "Challenge slug to create",
+          "name": "challenge",
+          "required": true
+        }
+      },
+      "description": "Create a new challenge locally and in the cloud",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-challenge"
+      ],
+      "flags": {
+        "verbose": {
+          "char": "v",
+          "description": "Verbose output",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:create",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "create.js"
+      ]
+    },
+    "challenge:delete": {
+      "aliases": [],
+      "args": {
+        "challenge": {
+          "description": "Challenge slug to delete",
+          "name": "challenge",
+          "required": true
+        }
+      },
+      "description": "Delete a challenge locally and from the cloud",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes"
+      ],
+      "flags": {
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:delete",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "delete.js"
+      ]
+    },
+    "challenge:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List all challenges (local and cloud)",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:list",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "list.js"
+      ]
+    },
+    "challenge:multi-upload": {
+      "aliases": [],
+      "args": {},
+      "description": "Interactively select and upload multiple challenges",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:multi-upload",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "multi-upload.js"
+      ]
+    },
+    "challenge:run": {
+      "aliases": [],
+      "args": {
+        "challenge": {
+          "description": "Challenge slug to run",
+          "name": "challenge",
+          "required": true
+        }
+      },
+      "description": "Run a challenge",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --studio"
+      ],
+      "flags": {
+        "studio": {
+          "char": "s",
+          "description": "Run in studio environment",
+          "name": "studio",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:run",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "run.js"
+      ]
+    },
+    "challenge:watch": {
+      "aliases": [],
+      "args": {
+        "challenge": {
+          "description": "Challenge slug to watch",
+          "name": "challenge",
+          "required": true
+        }
+      },
+      "description": "Watch a challenge for changes and auto-rebuild/upload",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-challenge"
+      ],
+      "flags": {
+        "verbose": {
+          "description": "Enable verbose output",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:watch",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "watch.js"
+      ]
+    }
+  },
+  "version": "0.0.2"
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+	"name": "@kradle/cli",
+	"version": "0.0.2",
+	"description": "Kradle's CLI. Manage challenges, evaluations, agents and more!",
+	"keywords": [
+		"cli"
+	],
+	"license": "AGPL-3.0",
+	"author": "Kradle",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"kradle": "bin/run.js"
+	},
+	"files": [
+		"./bin",
+		"./dist",
+		"./oclif.manifest.json",
+		"./static",
+		"./README.md"
+	],
+	"scripts": {
+		"build": "rm -rf dist && tsc",
+		"watch": "rm -rf dist && tsc --watch",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"prepack": "cp package.json package.json.bak && npm pkg delete bin.kradle-dev && npm run build && oclif manifest && oclif readme",
+		"postpack": "mv -f package.json.bak package.json && rm -f oclif.manifest.json",
+		"version": "oclif readme && git add README.md"
+	},
+	"dependencies": {
+		"@google-cloud/storage": "^7.17.3",
+		"@oclif/core": "^4.8.0",
+		"@oclif/plugin-autocomplete": "^3.2.39",
+		"@oclif/plugin-help": "^6.2.35",
+		"chokidar": "^4.0.3",
+		"dotenv": "^17.2.3",
+		"enquirer": "^2.4.1",
+		"listr2": "^9.0.5",
+		"picocolors": "^1.1.1",
+		"tar": "^7.5.2",
+		"zod": "^4.1.12"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.4",
+		"@oclif/test": "^4",
+		"@types/chai": "^4",
+		"@types/node": "^18",
+		"@types/tar": "^6.1.13",
+		"chai": "^4",
+		"oclif": "^4",
+		"tsx": "^4.20.6",
+		"typescript": "^5.9.3"
+	},
+	"engines": {
+		"node": ">=22.18.0"
+	},
+	"oclif": {
+		"bin": "kradle",
+		"dirname": "kradle",
+		"commands": "./dist/commands",
+		"plugins": [
+			"@oclif/plugin-help",
+			"@oclif/plugin-autocomplete"
+		],
+		"topicSeparator": " ",
+		"topics": {
+			"challenge": {
+				"description": "Manage challenges"
+			},
+			"agent": {
+				"description": "Manage agents"
+			}
+		}
+	}
+}

package/static/challenge.ts

@@ -0,0 +1,32 @@
+import { Actions, createChallenge, DEFAULT_CHALLENGE_PATH } from "@kradle/challenges";
+import { config } from "./config.ts";
+
+// Extract challenge name from config
+const challenge_name = config.slug.split(":").at(-1)!;
+const GAME_DURATION = 2 * 60 * 20; // 2 minutes
+
+createChallenge({
+	name: challenge_name,
+	kradle_challenge_path: process.env.KRADLE_CHALLENGES_PATH || DEFAULT_CHALLENGE_PATH,
+	GAME_DURATION: GAME_DURATION,
+	roles: ["all"],
+	custom_variables: {},
+})
+	.events(() => ({
+		start_challenge: {
+			actions: [Actions.announce({ message: ["Challenge starting!"] }), Actions.setTime({ time: "day" })],
+		},
+		init_participants: {
+			actions: [
+				Actions.clear({ target: "all" }),
+				Actions.setAttribute({ attribute_: "minecraft:generic.max_health", value: 20, target: "all" }),
+			],
+		},
+		end_challenge: {
+			actions: [Actions.announce({ message: ["Challenge ended!"] })],
+		},
+	}))
+	.end_condition(({ alive_players }) => alive_players.equalTo(0))
+	.win_conditions(({ has_never_died }, { all }) => ({
+		[all]: has_never_died.equalTo(1),
+	}));

package/static/project_template/dev.env

@@ -0,0 +1,6 @@
+WEB_API_URL=https://dev-api.kradle.ai/v0 #https://api.kradle.ai/v0
+WEB_URL=https://dev.kradle.ai #https:/.kradle.ai/workbench
+STUDIO_API_URL=http://localhost:2999/api/v0
+STUDIO_URL=kradle-dev://open #kradle://://open
+GCS_BUCKET=mckradle-3c267.firebasestorage.app #kradle-prod-storage
+KRADLE_CHALLENGES_PATH=~/Documents/kradle-studio/challenges

package/static/project_template/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "my-challenge",
+	"version": "1.0.0",
+	"description": "My challenge",
+	"dependencies": {
+		"@kradle/challenges": "latest",
+		"sandstone": "0.14.0-alpha.13"
+	},
+	"type": "module",
+	"devDependencies": {
+		"@types/node": "^18.14.0",
+		"typescript": "^5.9.3"
+	},
+	"engines": {
+		"node": ">=22.18.0"
+	}
+}

package/static/project_template/prod.env

@@ -0,0 +1,6 @@
+WEB_API_URL=https://api.kradle.ai/v0 #https://dev-api.kradle.ai/v0
+WEB_URL=https://kradle.ai #https://dev.kradle.ai
+STUDIO_API_URL=http://localhost:2999/api/v0
+STUDIO_URL=kradle://open #kradle-dev://://open
+GCS_BUCKET=kradle-prod-storage #mckradle-3c267.firebasestorage.app
+KRADLE_CHALLENGES_PATH=~/Documents/kradle-studio/challenges

package/static/project_template/template-run.json

@@ -0,0 +1,10 @@
+{
+    "participants": [
+        {
+            "agent": "team-kradle:gemini-2-5-flash"
+        },
+        {
+            "agent": "team-kradle:codestral-2508"
+        }
+    ]
+}

package/static/project_template/tsconfig.json

@@ -0,0 +1,17 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "CommonJS",
+		"outDir": "build",
+		"rootDir": ".",
+		"moduleResolution": "node",
+		"strict": true,
+		"esModuleInterop": true,
+		"allowJs": true,
+		"checkJs": false,
+		"skipLibCheck": true,
+		"allowImportingTsExtensions": true,
+		"noEmit": true
+	},
+	"include": ["challenges/**/*"]
+}