@kradle/cli 0.0.2

package/README.md

@@ -0,0 +1,224 @@
+# Kradle CLI
+
+Kradle's CLI for managing Minecraft challenges, evaluations, agents, and more!
+
+## Kradle - private installation
+
+1. Install Kradle's CLI globally
+```
+npm i -g @kradle/cli
+```
+2. Initialize a new project
+```
+kradle init
+```
+3. Congrats 🎉 You can now create a new challenge:
+```
+kradle challenge create <challenge-name>
+```
+
+In addition, you can enable [autocomplete](#Autocomplete).
+
+## Autocomplete
+
+Kradle CLI supports shell autocomplete for faster command entry. After installation, enable autocomplete for your shell:
+
+```bash
+kradle autocomplete
+# Follow the instructions printed
+```
+
+The command will display instructions for your specific shell.
+
+After setup, you will be able to use Tab to autocomplete:
+```bash
+kradle challenge <TAB>        # Shows: build, create, list, run, upload, watch, etc.
+```
+
+## Configuration
+
+The `.env` should have the following variables:
+
+```env
+WEB_API_URL=https://api.kradle.ai
+WEB_URL=https://kradle.ai
+STUDIO_API_URL=http://localhost:8080
+STUDIO_URL=kradle-studio://
+KRADLE_API_KEY=your-api-key
+GCS_BUCKET=your-gcs-bucket
+KRADLE_CHALLENGES_PATH=~/Documents/kradle-studio/challenges
+```
+
+## Commands
+
+### Create Challenge
+
+Create a new challenge locally and in the cloud:
+
+```bash
+kradle challenge create <challenge-name>
+```
+
+This creates a `challenges/<challenge-name>/` folder with:
+- `challenge.ts`: The entrypoint defining challenge behavior
+- `config.ts`: TypeScript file with challenge metadata (auto-generated from cloud API)
+
+### Build Challenge
+
+Build challenge datapack and upload both config and datapack:
+
+```bash
+kradle challenge build <challenge-name>
+```
+
+This command:
+1. Creates the challenge in the cloud (if it doesn't already exists)
+2. Uploads `config.ts` to cloud (if it exists)
+3. Builds the datapack by executing `challenge.ts`
+4. Uploads the datapack to GCS
+
+### Delete Challenge
+
+Delete a challenge locally, from the cloud, or both:
+
+```bash
+# Will ask confirmation for local & cloud deletion
+kradle challenge delete <challenge-name>
+
+# Doesn't ask for confirmation
+kradle challenge delete <challenge-name> --yes
+```
+
+### List Challenges
+
+List all challenges (local and cloud):
+
+```bash
+kradle challenge list
+```
+
+### Watch Challenge
+
+Watch a challenge for changes and auto-rebuild/upload:
+
+```bash
+kradle challenge watch <challenge-name>
+```
+
+Uses file watching with debouncing (300ms) and hash comparison to minimize unnecessary rebuilds.
+
+### Run Challenge
+
+Run a challenge in production or studio environment:
+
+```bash
+kradle challenge run <challenge-name>
+kradle challenge run <challenge-name> --studio  # Run in local studio environment
+```
+
+### Multi-Upload
+
+Interactively select and upload multiple challenges:
+
+```bash
+kradle challenge multi-upload
+```
+
+Provides an interactive UI to select multiple challenges and uploads them in parallel.
+
+## Development
+
+### Setup
+
+This CLI requires linking to be used locally:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+### `kradle` vs `kradle-dev`
+
+The repository provides two CLI commands:
+
+- **`kradle`**: Production CLI that runs compiled JavaScript from `dist/`
+  - Requires `npm run build` after every code change
+  - This is what end users will use
+
+- **`kradle-dev`**: Development CLI that runs TypeScript directly
+  - No build step required
+  - Changes are reflected immediately
+  - **Always use this during development**
+
+Example usage:
+```bash
+kradle-dev challenge list
+kradle-dev challenge build <challenge-name>
+kradle-dev challenge run <challenge-name>
+```
+
+### Build & Lint
+
+```bash
+npm run build              # Compile TypeScript to dist/
+npm run lint               # Check for linting issues
+npm run lint:fix           # Auto-fix linting issues
+npm run format             # Format code with Biome
+```
+
+### Challenge Structure
+
+Each challenge is a folder in `challenges/<slug>/` containing:
+
+- **`challenge.ts`**: Entrypoint that defines challenge behavior using the Sandstone API
+- **`config.ts`**: TypeScript file exporting challenge metadata (name, visibility, roles, objectives, etc.)
+
+**Workflow:**
+1. `kradle challenge create <slug>` creates the folder with `challenge.ts`
+2. The create command automatically builds, uploads, and downloads the config from the cloud API
+3. The downloaded JSON is converted into a typed TypeScript `config.ts` file
+4. `kradle challenge build <slug>` automatically uploads `config.ts` (if it exists) before building the datapack
+5. You can modify `config.ts` locally and run `build` to sync changes to the cloud
+
+### Configuration Note
+
+The CLI relies on a `.env` file in the **parent directory (kradle-sandstone root)**, not in the kradle-cli directory itself. The `.env` file should be at the same level as both `kradle-cli/` and `challenges/` folders.
+
+## Architecture
+
+The CLI is built with:
+
+- **oclif**: CLI framework
+- **enquirer**: Interactive prompts
+- **listr2**: Task list UI
+- **picocolors**: Terminal colors
+- **zod**: Schema validation
+- **chokidar**: File watching
+- **biome**: Linting and formatting
+
+### Project Structure
+
+```
+kradle-cli/
+├── src/
+│   ├── commands/             # CLI commands
+│   │   └── challenge/        # Challenge management commands
+│   │       ├── build.ts      # Build & upload datapack + config
+│   │       ├── create.ts     # Create new challenge
+│   │       ├── list.ts       # List local & cloud challenges
+│   │       ├── multi-upload.ts  # Interactive multi-select upload
+│   │       ├── run.ts        # Run challenge (prod or studio)
+│   │       ├── watch.ts      # Watch for changes & auto-rebuild
+│   └── lib/                  # Core libraries
+│       ├── api-client.ts     # Typed API client with Zod validation
+│       ├── arguments.ts      # Shared CLI arguments with autocomplete
+│       ├── challenge.ts      # Challenge class (build, upload, hash, config)
+│       ├── config.ts         # Environment config with Zod schemas
+│       ├── schemas.ts        # Zod schemas for type-safe API interactions
+│       └── utils.ts          # Utility functions
+├── static/                   # Template files (challenge.ts)
+├── biome.json               # Biome linter & formatter config
+├── package.json
+└── tsconfig.json            # TypeScript ESM configuration
+```

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+npx --yes tsx "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S npx --yes tsx
+
+import { execute } from "@oclif/core";
+import path from "node:path";
+import fs from "node:fs";
+import dotenv from "dotenv";
+
+// Load .env file from cwd if it exists
+const envPath = path.join(process.cwd(), ".env");
+if (fs.existsSync(envPath)) {
+	dotenv.config({ path: envPath, quiet: true });
+}
+
+await execute({ development: true, dir: import.meta.url });

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node --no-warnings
+
+import { execute } from "@oclif/core";
+import path from "node:path";
+import fs from "node:fs";
+import dotenv from "dotenv";
+
+// Load .env file from cwd if it exists
+const envPath = path.join(process.cwd(), ".env");
+if (fs.existsSync(envPath)) {
+	dotenv.config({ path: envPath, quiet: true });
+}
+
+await execute({ dir: import.meta.url });

package/dist/commands/agent/list.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class List extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/agent/list.js

@@ -0,0 +1,20 @@
+import { Command } from "@oclif/core";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { loadConfig } from "../../lib/config.js";
+export default class List extends Command {
+    static description = "List all agents";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        const config = loadConfig();
+        await this.parse(List);
+        const api = new ApiClient(config);
+        this.log(pc.blue(">> Loading agents..."));
+        const agents = await api.listKradleAgents();
+        agents.sort((a, b) => a.username?.localeCompare(b.username || "") || 0);
+        this.log(pc.bold(`\nFound ${agents.length} agents:\n`));
+        for (const agent of agents) {
+            this.log(pc.bold(`- ${agent.username}`));
+        }
+    }
+}

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

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

package/dist/commands/challenge/build.js

@@ -0,0 +1,25 @@
+import { Command } 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";
+export default class Build extends Command {
+    static description = "Build and upload challenge datapack and config";
+    static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
+    static args = {
+        challenge: getChallengeSlugArgument({ description: "Challenge slug to build" }),
+    };
+    async run() {
+        const { args } = await this.parse(Build);
+        const config = loadConfig();
+        const api = new ApiClient(config);
+        const challenge = new Challenge(args.challenge, config);
+        try {
+            await challenge.buildAndUpload(api);
+        }
+        catch (error) {
+            this.error(pc.red(`Build failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

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

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

package/dist/commands/challenge/create.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import { Command, Flags } from "@oclif/core";
+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";
+export default class Create extends Command {
+    static description = "Create a new challenge locally and in the cloud";
+    static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
+    static args = {
+        challenge: getChallengeSlugArgument({ description: "Challenge slug to create" }),
+    };
+    static flags = {
+        verbose: Flags.boolean({ char: "v", description: "Verbose output", default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Create);
+        const config = loadConfig();
+        const api = new ApiClient(config);
+        const challenge = new Challenge(args.challenge, config);
+        const tasks = new Listr([
+            {
+                title: "Checking if challenge exists",
+                task: async (_, task) => {
+                    const exists = await api.challengeExists(args.challenge);
+                    if (exists) {
+                        this.error(pc.red(`Challenge already exists: ${args.challenge}`));
+                    }
+                    task.title = `Challenge does not exist.`;
+                },
+            },
+            {
+                title: "Creating local challenge folder",
+                task: async (_, task) => {
+                    await Challenge.createLocal(args.challenge, config);
+                    task.title = `Created local challenge folder: ${challenge.challengeDir}`;
+                },
+            },
+            {
+                title: "Creating cloud challenge",
+                task: async (_, task) => {
+                    await api.createChallenge(args.challenge);
+                    task.title = `Created cloud challenge`;
+                },
+            },
+            {
+                title: "Downloading challenge config",
+                task: async (_, task) => {
+                    const challengeData = await api.getChallenge(args.challenge);
+                    // Remove fields that shouldn't be in the config file
+                    const { id, creationTime, updateTime, creator, ...cleanChallenge } = challengeData;
+                    // Remove quotes from keys
+                    const configStr = JSON.stringify(cleanChallenge, null, 2).replace(/"([a-zA-Z0-9_]+)":/g, "$1:");
+                    await fs.writeFile(challenge.configPath, `
+export const config = ${configStr};
+`.trim());
+                    task.title = `Downloaded config to: ${challenge.configPath}`;
+                },
+            },
+            {
+                title: "Building initial datapack",
+                task: async (_, task) => {
+                    await challenge.build(!flags.verbose);
+                    task.title = `Built initial datapack`;
+                },
+            },
+            {
+                title: "Uploading initial datapack",
+                task: async (_, task) => {
+                    await challenge.upload(api);
+                    task.title = `Uploaded initial datapack`;
+                },
+            },
+        ]);
+        try {
+            await tasks.run();
+            this.log(pc.green(`\n✓ Challenge created: ${args.challenge}`));
+            this.log(pc.green(`↳ Run "kradle challenge watch ${args.challenge}" to watch your challenge and start testing!`));
+            this.log(pc.dim(`\nSee your challenge at: ${config.WEB_URL}/studio/challenges/${args.challenge}?tab=challenge-definition`));
+        }
+        catch (error) {
+            this.error(pc.red(`Create failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

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

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

package/dist/commands/challenge/delete.js

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+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";
+export default class Delete extends Command {
+    static description = "Delete a challenge locally and from the cloud";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes",
+    ];
+    static args = {
+        challenge: getChallengeSlugArgument({ description: "Challenge slug to delete" }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Delete);
+        const config = loadConfig();
+        const api = new ApiClient(config);
+        const challenge = new Challenge(args.challenge, config);
+        // Check if challenge exists locally
+        const existsLocally = challenge.exists();
+        // Check if challenge exists in cloud
+        const existsInCloud = await api.challengeExists(challenge.shortSlug);
+        // If challenge doesn't exist anywhere, inform user and exit
+        if (!existsLocally && !existsInCloud) {
+            this.error(pc.red(`Challenge "${challenge.shortSlug}" does not exist locally or in the cloud.`));
+        }
+        // Show what will be deleted
+        this.log(pc.bold(`\nChallenge: ${pc.cyan(challenge.shortSlug)}`));
+        this.log(`  💻 Local:  ${existsLocally ? pc.green("✓ exists") : pc.dim("✗ not found")}`);
+        this.log(`  ☁️  Cloud:  ${existsInCloud ? pc.green("✓ exists") : pc.dim("✗ not found")}`);
+        this.log("");
+        // Confirm deletion from cloud
+        if (existsInCloud) {
+            if (!flags.yes) {
+                try {
+                    const response = await enquirer.prompt({
+                        type: "confirm",
+                        name: "confirm",
+                        message: `Delete challenge from cloud? ${pc.red("This cannot be undone.")}`,
+                        initial: false,
+                    });
+                    if (!response.confirm) {
+                        this.log(pc.yellow("✗ Cloud deletion cancelled"));
+                        return;
+                    }
+                }
+                catch (error) {
+                    this.log(pc.yellow("\n✗ Cloud deletion cancelled"));
+                    return;
+                }
+            }
+            try {
+                this.log(pc.blue(">> Deleting from cloud..."));
+                await api.deleteChallenge(challenge.shortSlug);
+                this.log(pc.green("✓ Deleted from cloud"));
+            }
+            catch (error) {
+                this.error(pc.red(`Failed to delete from cloud: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        // Confirm deletion locally
+        if (existsLocally) {
+            if (!flags.yes) {
+                try {
+                    const response = await enquirer.prompt({
+                        type: "confirm",
+                        name: "confirm",
+                        message: `Delete local challenge folder? ${pc.red("This cannot be undone.")}`,
+                        initial: false,
+                    });
+                    if (!response.confirm) {
+                        this.log(pc.yellow("✗ Local deletion cancelled"));
+                        return;
+                    }
+                }
+                catch (error) {
+                    this.log(pc.yellow("\n✗ Local deletion cancelled"));
+                    return;
+                }
+            }
+            try {
+                this.log(pc.blue(">> Deleting local folder..."));
+                await fs.rm(challenge.challengeDir, { recursive: true, force: true });
+                this.log(pc.green("✓ Deleted local folder"));
+            }
+            catch (error) {
+                this.error(pc.red(`Failed to delete local folder: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        this.log(pc.green(`\n✓ Challenge "${challenge.shortSlug}" deleted successfully!`));
+    }
+}

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

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class List extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/challenge/list.js

@@ -0,0 +1,48 @@
+import { Command } from "@oclif/core";
+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 List extends Command {
+    static description = "List all challenges (local and cloud)";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        const config = loadConfig();
+        await this.parse(List);
+        const api = new ApiClient(config);
+        this.log(pc.blue(">> Loading challenges..."));
+        const [cloudChallenges, localChallenges, human] = await Promise.all([
+            api.listChallenges(),
+            Challenge.getLocalChallenges(),
+            api.getHuman(),
+        ]);
+        // Create a map for easy lookup
+        const cloudMap = new Map(cloudChallenges.map((c) => [c.slug, c]));
+        const allSlugs = new Set([
+            ...cloudMap.keys(),
+            ...Object.keys(localChallenges).map((id) => `${human.username}:${id}`),
+        ]);
+        this.log(pc.bold("\nChallenges:\n"));
+        this.log(`${"Status".padEnd(15)} ${"Slug".padEnd(40)} ${"Name".padEnd(30)}`);
+        this.log("-".repeat(90));
+        for (const slug of Array.from(allSlugs).sort()) {
+            const challenge = new Challenge(slug, config);
+            const inCloud = cloudMap.has(slug);
+            const inLocal = localChallenges[challenge.shortSlug];
+            let status;
+            if (inCloud && inLocal) {
+                status = pc.green("✓ synced");
+            }
+            else if (inCloud) {
+                status = pc.yellow("☁ cloud only");
+            }
+            else {
+                status = pc.blue("⊡ local only");
+            }
+            const cloudChallenge = cloudMap.get(slug);
+            const name = cloudChallenge?.name || "-";
+            this.log(`${status.padEnd(24)} ${slug.padEnd(40)} ${name.padEnd(30)}`);
+        }
+        this.log(pc.dim(`\nTotal: ${allSlugs.size} challenges`));
+    }
+}

package/dist/commands/challenge/multi-upload.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class MultiUpload extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}