kradle 0.4.3 → 0.6.0

package/README.md

@@ -22,7 +22,7 @@ Make sure you have [NodeJS 22.18 or higher](https://nodejs.org/en/download/curre
 
 1. Install Kradle's CLI globally
 ```
-npm i -g kradle
+npm i -g kradle@latest
 ```
 2. Initialize a new directory to store challenges, and other Kradle resources:
 ```
@@ -138,16 +138,34 @@ Uses file watching with debouncing (300ms) and hash comparison to minimize unnec
 
 ### Run Challenge
 
-Run a challenge and wait for completion:
+Run a challenge with agents specified inline or via interactive selection:
 
 ```bash
+# Interactive mode - prompts for agent selection
 kradle challenge run <challenge-name>
+
+# Inline agent specification
+kradle challenge run <challenge-name> team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast
+
+# Team-based challenge with roles
+kradle challenge run capture-the-flag \
+  red=team-kradle:gemini-3-flash \
+  blue=team-kradle:claude-sonnet-4
+
+# Other options
 kradle challenge run <challenge-name> --studio     # Run in local studio environment
 kradle challenge run <team-name>:<challenge-name>  # Run a public challenge from another team
 kradle challenge run <challenge-name> --no-open    # Don't open browser
 kradle challenge run <challenge-name> --no-wait    # Fire and forget (don't wait for completion)
 ```
 
+**Inline Agent Syntax:**
+- `agent1,agent2` - Assign agents to the "default" role
+- `role=agent1,agent2` - Assign agents to a specific role
+- Same role can be specified multiple times and agents are merged
+
+When no agents are specified, the command enters interactive mode, fetching the challenge configuration and prompting for agent selection for each role.
+
 By default, the command opens the run URL in your browser and polls until the run completes, then displays the outcome.
 
 ### List Runs
@@ -165,12 +183,14 @@ Get details and logs for a specific run:
 
 ```bash
 kradle challenge runs get <run-id>
-kradle challenge runs get <run-id> --no-logs   # Skip fetching logs
+kradle challenge runs get <run-id> --no-logs      # Skip fetching logs
+kradle challenge runs get <run-id> --no-summary   # Skip AI summary
 ```
 
 This displays:
 - Run metadata (status, duration, end state)
 - Participant results (agent, winner status, score)
+- AI-generated summary (unless `--no-summary` is used)
 - Log entries with timestamps and levels (unless `--no-logs` is used)
 
 ## Experiment Commands

package/dist/commands/challenge/build.js

@@ -1,7 +1,7 @@
 import { Command, Flags, loadHelpClass } from "@oclif/core";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
-import { getChallengeSlugArgument } from "../../lib/arguments.js";
+import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Build extends Command {
@@ -39,7 +39,12 @@ export default class Build extends Command {
         const challengeSlugs = flags.all ? await Challenge.getLocalChallenges() : argv;
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         for (const challengeSlug of challengeSlugs) {
-            const challenge = new Challenge(challengeSlug, flags["challenges-path"]);
+            // Validate that the challenge exists locally
+            const validation = await Challenge.validateForLocalOperation(challengeSlug, flags["challenges-path"]);
+            if (!validation.isValid && validation.error) {
+                this.error(pc.red(validation.error));
+            }
+            const challenge = new Challenge(extractShortSlug(challengeSlug), flags["challenges-path"]);
             this.log(pc.blue(`==== Building challenge: ${challenge.shortSlug} ====`));
             try {
                 await challenge.buildAndUpload(api, flags.public);

package/dist/commands/challenge/create.js

@@ -11,7 +11,7 @@ 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 = {
-        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to create" }),
+        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to create", strictLocalSlug: true }),
     };
     static flags = {
         verbose: Flags.boolean({ char: "v", description: "Verbose output", default: false }),

package/dist/commands/challenge/delete.js

@@ -3,7 +3,7 @@ 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 { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Delete extends Command {
@@ -22,17 +22,18 @@ export default class Delete extends Command {
     async run() {
         const { args, flags } = await this.parse(Delete);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
-        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
-        // Check if challenge exists locally
+        const shortSlug = extractShortSlug(args.challengeSlug);
+        const challenge = new Challenge(shortSlug, flags["challenges-path"]);
+        // Check if challenge exists locally (always uses short slug)
         const existsLocally = challenge.exists();
-        // Check if challenge exists in cloud
-        const existsInCloud = await api.challengeExists(challenge.shortSlug);
+        // Check if challenge exists in cloud (use full slug to support namespaced challenges)
+        const existsInCloud = await api.challengeExists(args.challengeSlug);
         // 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.`));
+            this.error(pc.red(`Challenge "${args.challengeSlug}" does not exist locally or in the cloud.`));
         }
         // Show what will be deleted
-        this.log(pc.bold(`\nChallenge: ${pc.cyan(challenge.shortSlug)}`));
+        this.log(pc.bold(`\nChallenge: ${pc.cyan(args.challengeSlug)}`));
         this.log(`  💻 Local:  ${existsLocally ? pc.green("✓ exists") : pc.dim("✗ not found")}`);
         this.log(`  ☁️  Cloud:  ${existsInCloud ? pc.green("✓ exists") : pc.dim("✗ not found")}`);
         this.log("");
@@ -58,7 +59,7 @@ export default class Delete extends Command {
             }
             try {
                 this.log(pc.blue(">> Deleting from cloud..."));
-                await api.deleteChallenge(challenge.shortSlug);
+                await api.deleteChallenge(args.challengeSlug);
                 this.log(pc.green("✓ Deleted from cloud"));
             }
             catch (error) {
@@ -94,6 +95,6 @@ export default class Delete extends Command {
                 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!`));
+        this.log(pc.green(`\n✓ Challenge "${args.challengeSlug}" deleted successfully!`));
     }
 }

package/dist/commands/challenge/pull.js

@@ -20,7 +20,6 @@ export default class Pull extends Command {
         challengeSlug: getChallengeSlugArgument({
             description: "Challenge slug to pull (interactive selection if omitted)",
             required: false,
-            allowTeam: true,
         }),
     };
     static flags = {

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

@@ -1,6 +1,7 @@
 import { Command } from "@oclif/core";
 export default class Run extends Command {
     static description: string;
+    static strict: boolean;
     static examples: string[];
     static args: {
         challengeSlug: import("@oclif/core/interfaces").Arg<string>;
@@ -18,5 +19,18 @@ export default class Run extends Command {
     };
     private pollForCompletion;
     private displayRunResult;
+    /**
+     * Parse inline agent arguments into participants.
+     * Supports formats:
+     * - team=agent1,agent2 -> assigns agents to a role/team
+     * - agent1,agent2 -> assigns agents to "default" role
+     * Same team can be specified multiple times and agents are merged.
+     */
+    private parseInlineAgents;
+    /**
+     * Interactive agent selection when no agents are specified inline.
+     * Fetches challenge config from cloud and prompts user to select agents for each role.
+     */
+    private selectAgentsInteractively;
     run(): Promise<void>;
 }

package/dist/commands/challenge/run.js

@@ -1,25 +1,29 @@
 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 { getConfigFlags } from "../../lib/flags.js";
-import { formatDuration, getRunStatusDisplay, loadTemplateRun, openInBrowser } from "../../lib/utils.js";
+import { clearScreen, formatDuration, fuzzyHighlight, getRunStatusDisplay, openInBrowser } from "../../lib/utils.js";
 const POLL_INTERVAL_MS = 2000;
 const MAX_POLL_TIME_MS = 30 * 60 * 1000; // 30 minutes
 const TERMINAL_STATUSES = ["finished", "game_over", "error", "completed", "cancelled", "timeout", "failed"];
 export default class Run extends Command {
     static description = "Run a challenge";
+    // Allow variadic arguments for inline agent specification
+    static strict = false;
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
         "<%= config.bin %> <%= command.id %> team-name:my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --no-open",
         "<%= config.bin %> <%= command.id %> my-challenge --no-wait",
+        "<%= config.bin %> <%= command.id %> my-challenge team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast",
+        "<%= config.bin %> <%= command.id %> capture-the-flag red=team-kradle:gemini-3-flash blue=team-kradle:grok-4-1-fast",
     ];
     static args = {
         challengeSlug: getChallengeSlugArgument({
             description: "Challenge slug to run (e.g., 'my-challenge' or 'team-name:my-challenge')",
-            allowTeam: true,
         }),
     };
     static flags = {
@@ -101,15 +105,178 @@ export default class Run extends Command {
             this.log(result.summary);
         }
     }
+    /**
+     * Parse inline agent arguments into participants.
+     * Supports formats:
+     * - team=agent1,agent2 -> assigns agents to a role/team
+     * - agent1,agent2 -> assigns agents to "default" role
+     * Same team can be specified multiple times and agents are merged.
+     */
+    parseInlineAgents(agentArgs) {
+        const roleAgents = new Map();
+        for (const arg of agentArgs) {
+            let role;
+            let agentsStr;
+            if (arg.includes("=")) {
+                // Format: team=agent1,agent2
+                const eqIndex = arg.indexOf("=");
+                role = arg.slice(0, eqIndex);
+                agentsStr = arg.slice(eqIndex + 1);
+            }
+            else {
+                // Format: agent1,agent2 (no team specified, use "default")
+                role = "default";
+                agentsStr = arg;
+            }
+            const agents = agentsStr.split(",").filter((a) => a.length > 0);
+            // Merge with existing agents for this role
+            const existing = roleAgents.get(role) || [];
+            roleAgents.set(role, [...existing, ...agents]);
+        }
+        // Convert to participants array
+        const participants = [];
+        for (const [role, agents] of roleAgents) {
+            for (const agent of agents) {
+                participants.push({ agent, role });
+            }
+        }
+        return participants;
+    }
+    /**
+     * Interactive agent selection when no agents are specified inline.
+     * Fetches challenge config from cloud and prompts user to select agents for each role.
+     */
+    async selectAgentsInteractively(challenge, availableAgents) {
+        const participants = [];
+        const roles = challenge.roles;
+        const roleNames = Object.keys(roles);
+        // All selected agents across all roles - this is used to display already-selected agents at the top of the prompt
+        const allSelectedAgents = [];
+        // Build agent choices for the prompt
+        const agentChoices = availableAgents
+            .filter((a) => a.username !== undefined)
+            .map((a) => ({
+            name: a.username,
+            message: a.username,
+        }));
+        if (agentChoices.length === 0) {
+            this.error("No agents available. Please check your API key and permissions.");
+        }
+        const COLORS = [pc.yellow, pc.magenta, pc.cyan, pc.green, pc.blue, pc.red];
+        for (let i = 0; i < roleNames.length; i++) {
+            const roleName = roleNames[i];
+            const color = COLORS[i % COLORS.length];
+            const roleConfig = roles[roleName];
+            const min = roleConfig.minParticipants;
+            const max = roleConfig.maxParticipants;
+            // Build prompt message
+            let message = `Select agents for role "${pc.bold(color(roleName))}"`;
+            if (min !== undefined && max !== undefined) {
+                message += ` (min: ${min}, max: ${max})`;
+            }
+            else if (min !== undefined) {
+                message += ` (min: ${min})`;
+            }
+            else if (max !== undefined) {
+                message += ` (max: ${max})`;
+            }
+            // Use autocomplete for searchable selection with multiple selections
+            const selectedAgents = [];
+            let selecting = true;
+            while (selecting) {
+                clearScreen();
+                agentChoices.sort((a, b) => {
+                    // First, display already-selected agents at the top
+                    if (allSelectedAgents.includes(a.name))
+                        return -1;
+                    if (allSelectedAgents.includes(b.name))
+                        return 1;
+                    // Then sort by name
+                    return a.message.localeCompare(b.message);
+                });
+                const response = await enquirer.prompt({
+                    type: "autocomplete",
+                    name: "agent",
+                    message: selectedAgents.length > 0 ? `${message} [${selectedAgents.length} selected]` : message,
+                    // @ts-expect-error - somehow this is not typed correctly
+                    limit: 10,
+                    choices: [
+                        ...(selectedAgents.length >= (min ?? 1)
+                            ? [{ name: "__done__", message: pc.green("✓ Done selecting") }]
+                            : []),
+                        ...agentChoices,
+                    ],
+                    suggest: (input, choices) => {
+                        if (!input)
+                            return choices;
+                        return choices.flatMap((choice) => {
+                            if (choice.name === "__done__")
+                                return [choice];
+                            const highlighted = fuzzyHighlight(input, choice.message, pc.red);
+                            return highlighted ? [{ ...choice, message: highlighted }] : [];
+                        });
+                    },
+                    footer: () => {
+                        let currentlySelectedString = "";
+                        if (selectedAgents.length > 0) {
+                            const groupedAgents = Object.groupBy(selectedAgents, (agent) => agent);
+                            currentlySelectedString = `\nCurrently selected: ${Object.entries(groupedAgents)
+                                .map(([agent, arr]) => (arr?.length === 1 ? agent : `${agent} x${arr?.length}`))
+                                .join(", ")}`;
+                        }
+                        return pc.dim(`Type to search for agents, press Enter to select, or press Ctrl+C to cancel.${currentlySelectedString}`);
+                    },
+                });
+                if (response.agent === "__done__") {
+                    selecting = false;
+                }
+                else {
+                    selectedAgents.push(response.agent);
+                    allSelectedAgents.push(response.agent);
+                    // If max is defined and reached, stop selecting
+                    if (max !== undefined && selectedAgents.length >= max) {
+                        selecting = false;
+                    }
+                }
+            }
+            // Validate minimum
+            if (min !== undefined && selectedAgents.length < min) {
+                this.error(`Role "${roleName}" requires at least ${min} agents, but only ${selectedAgents.length} selected.`);
+            }
+            // Add participants for this role
+            for (const agent of selectedAgents) {
+                participants.push({ agent, role: roleName });
+            }
+        }
+        return participants;
+    }
     async run() {
-        const { args, flags } = await this.parse(Run);
+        const { args, flags, argv } = await this.parse(Run);
         const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
-        const studioApi = new ApiClient(apiUrl, flags["api-key"]);
+        const api = new ApiClient(apiUrl, flags["api-key"]);
         const challengeSlug = args.challengeSlug;
+        // Get extra arguments (after the challenge slug) for inline agent specification
+        const agentArgs = argv.filter((arg) => arg !== challengeSlug);
+        let participants;
+        if (agentArgs.length > 0) {
+            // Parse inline agent specification
+            participants = this.parseInlineAgents(agentArgs);
+        }
+        else {
+            // Interactive mode: fetch challenge config and prompt for agents
+            this.log(pc.blue(`>> Fetching challenge configuration...`));
+            const [challenge, availableAgents] = await Promise.all([api.getChallenge(challengeSlug), api.listKradleAgents()]);
+            this.log(pc.dim(`Challenge: ${challenge.name}`));
+            this.log(pc.dim(`Roles: ${Object.keys(challenge.roles).join(", ")}`));
+            this.log("");
+            participants = await this.selectAgentsInteractively(challenge, availableAgents);
+        }
+        if (participants.length === 0) {
+            this.error("No participants specified. Use inline syntax or select agents interactively.");
+        }
         try {
-            const { participants } = (await loadTemplateRun());
-            this.log(pc.blue(`>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
-            const response = await studioApi.runChallenge({
+            this.log(pc.blue(`\n>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
+            const response = await api.runChallenge({
                 challenge: challengeSlug,
                 participants,
                 jobType: "foreground",
@@ -118,7 +285,7 @@ export default class Run extends Command {
                 const runId = response.runIds[0];
                 const baseUrl = flags.studio ? flags["studio-url"] : flags["web-url"];
                 const runUrl = `${baseUrl}/runs/${runId}`;
-                this.log(pc.green("\n\u2713 Challenge started!"));
+                this.log(pc.green("\n✓ Challenge started!"));
                 this.log(pc.dim(`Run ID: ${runId}`));
                 this.log(pc.dim(`Run URL: ${runUrl}`));
                 if (!flags["no-open"]) {
@@ -126,11 +293,11 @@ export default class Run extends Command {
                 }
                 if (!flags["no-wait"]) {
                     this.log(pc.blue("\n>> Waiting for run to complete...\n"));
-                    await this.pollForCompletion(studioApi, runId, !flags["no-summary"]);
+                    await this.pollForCompletion(api, runId, !flags["no-summary"]);
                 }
             }
             else {
-                this.log(pc.yellow("\u26a0 Challenge started but no run ID returned"));
+                this.log(pc.yellow("⚠ Challenge started but no run ID returned"));
             }
         }
         catch (error) {

package/dist/commands/challenge/runs/get.d.ts

@@ -9,6 +9,7 @@ export default class GetRun extends Command {
         "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "no-logs": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-summary": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/challenge/runs/get.js

@@ -29,6 +29,7 @@ export default class GetRun extends Command {
     static examples = [
         "<%= config.bin %> <%= command.id %> abc123",
         "<%= config.bin %> <%= command.id %> abc123 --no-logs",
+        "<%= config.bin %> <%= command.id %> abc123 --no-summary",
     ];
     static args = {
         runId: Args.string({
@@ -41,12 +42,17 @@ export default class GetRun extends Command {
             description: "Skip fetching and displaying logs",
             default: false,
         }),
+        "no-summary": Flags.boolean({
+            description: "Skip displaying the AI-generated summary",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url"),
     };
     async run() {
         const { args, flags } = await this.parse(GetRun);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         const showLogs = !flags["no-logs"];
+        const showSummary = !flags["no-summary"];
         this.log(pc.blue(`>> Loading run ${args.runId}...`));
         try {
             const [runResult, logs] = await Promise.all([
@@ -88,6 +94,11 @@ export default class GetRun extends Command {
                     this.log(`${participantId.padEnd(widths[0])} ${agentPadded} ${winner} ${score.padEnd(widths[3])} ${timeToSuccess}`);
                 }
             }
+            // AI Summary
+            if (showSummary && runResult.summary) {
+                this.log(pc.bold("\n=== Summary ===\n"));
+                this.log(runResult.summary);
+            }
             // Logs
             if (showLogs) {
                 if (logs.length > 0) {

package/dist/commands/challenge/watch.js

@@ -4,7 +4,7 @@ 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 { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 import { clearScreen, debounced } from "../../lib/utils.js";
@@ -20,7 +20,12 @@ export default class Watch extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Watch);
-        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
+        // Validate that the challenge exists locally
+        const validation = await Challenge.validateForLocalOperation(args.challengeSlug, flags["challenges-path"]);
+        if (!validation.isValid && validation.error) {
+            this.error(pc.red(validation.error));
+        }
+        const challenge = new Challenge(extractShortSlug(args.challengeSlug), flags["challenges-path"]);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         const debounceSeconds = 1;
         let building = false;
@@ -57,7 +62,7 @@ export default class Watch extends Command {
                 {
                     title: "Building datapack",
                     task: async (_ctx, task) => {
-                        await challenge.build(!flags.verbose);
+                        await challenge.build(!flags.verbose, lastConfig);
                         task.title = "Datapack built";
                     },
                 },

package/dist/commands/world/import.js

@@ -59,6 +59,8 @@ export default class Import extends Command {
             this.log(`World "${slug}" already exists. Re-import will update the tarball but preserve config.ts.`);
         }
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        // Context to share data between tasks
+        const ctx = {};
         const tasks = new Listr([
             {
                 title: "Creating world directory",
@@ -82,26 +84,32 @@ export default class Import extends Command {
                 },
             },
             {
-                title: "Creating world in cloud",
-                enabled: () => !isReimport,
+                title: "Ensuring world exists in cloud",
                 task: async (_ctx, task) => {
                     const exists = await api.worldExists(slug);
-                    if (exists) {
-                        task.title = "World already exists in cloud";
-                        return;
+                    if (!exists) {
+                        const config = {
+                            name: slug,
+                            domain: "minecraft",
+                        };
+                        const cloudWorld = await api.createWorld(slug, config);
+                        ctx.worldId = cloudWorld.id;
+                        task.title = "Created world in cloud";
+                    }
+                    else {
+                        const cloudWorld = await api.getWorld(slug);
+                        ctx.worldId = cloudWorld.id;
+                        task.title = "World exists in cloud";
                     }
-                    const config = {
-                        name: slug,
-                        domain: "minecraft",
-                    };
-                    await api.createWorld(slug, config);
-                    task.title = "Created world in cloud";
                 },
             },
             {
                 title: "Uploading world to cloud",
                 task: async (_ctx, task) => {
-                    await api.uploadWorldFile(slug, world.tarballPath);
+                    if (!ctx.worldId) {
+                        throw new Error("Missing world ID");
+                    }
+                    await api.uploadWorldFile(slug, sourcePath, ctx.worldId);
                     task.title = "Uploaded world to cloud";
                 },
             },

package/dist/commands/world/pull.js

@@ -20,7 +20,6 @@ export default class Pull extends Command {
         worldSlug: getWorldSlugArgument({
             description: "World slug to pull (interactive selection if omitted)",
             required: false,
-            allowTeam: true,
         }),
     };
     static flags = {
@@ -111,6 +110,13 @@ export default class Pull extends Command {
                     task.title = "Downloaded world";
                 },
             },
+            {
+                title: "Normalizing tarball structure",
+                task: async (_ctx, task) => {
+                    await world.normalizeDownloadedTarball();
+                    task.title = "Tarball structure normalized";
+                },
+            },
             {
                 title: "Creating config.ts",
                 task: async (_ctx, task) => {

package/dist/commands/world/push.js

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import { Command, Flags, loadHelpClass } from "@oclif/core";
 import { Listr } from "listr2";
 import pc from "picocolors";
@@ -65,6 +66,8 @@ export default class Push extends Command {
                 continue;
             }
             const config = await world.loadConfig();
+            // Context to share data between tasks
+            const ctx = {};
             const tasks = new Listr([
                 {
                     title: "Ensuring world exists in cloud",
@@ -83,6 +86,7 @@ export default class Push extends Command {
                     title: "Checking world visibility",
                     task: async (_ctx, task) => {
                         const cloudWorld = await api.getWorld(worldSlug);
+                        ctx.worldId = cloudWorld.id;
                         if (cloudWorld.visibility === "public") {
                             task.title = "World is public, setting to private for update...";
                             await api.updateWorldVisibility(worldSlug, "private");
@@ -100,10 +104,20 @@ export default class Push extends Command {
                         task.title = "Config uploaded";
                     },
                 },
+                {
+                    title: "Extracting world tarball",
+                    task: async (_ctx, task) => {
+                        ctx.extractedDir = await world.extractToTempDir();
+                        task.title = "World tarball extracted";
+                    },
+                },
                 {
                     title: "Uploading world",
                     task: async (_ctx, task) => {
-                        await api.uploadWorldFile(worldSlug, world.tarballPath);
+                        if (!ctx.worldId || !ctx.extractedDir) {
+                            throw new Error("Missing world ID or extracted directory");
+                        }
+                        await api.uploadWorldFile(worldSlug, ctx.extractedDir, ctx.worldId);
                         task.title = "World uploaded";
                     },
                 },
@@ -116,7 +130,15 @@ export default class Push extends Command {
                     },
                 },
             ]);
-            await tasks.run();
+            try {
+                await tasks.run();
+            }
+            finally {
+                // Clean up extracted directory
+                if (ctx.extractedDir) {
+                    await fs.rm(ctx.extractedDir, { recursive: true, force: true });
+                }
+            }
             this.log(pc.green(`✓ World pushed: ${worldSlug}`));
             this.log();
         }

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

@@ -150,7 +150,15 @@ export declare class ApiClient {
     deleteWorld(slug: string): Promise<void>;
     getWorldUploadUrl(slug: string): Promise<string>;
     getWorldDownloadUrl(slug: string): Promise<DownloadUrlResponse>;
-    uploadWorldFile(slug: string, tarballPath: string): Promise<void>;
+    /**
+     * Upload a world folder to Google Cloud Storage.
+     * The folder must contain level.dat at its root.
+     * The tarball will be created with the world ID as the root folder (e.g., {worldId}/level.dat).
+     * @param slug - The slug of the world (used to get the upload URL).
+     * @param worldFolderPath - Path to the world folder containing level.dat at root.
+     * @param worldId - The world ID to use as the root folder in the tarball.
+     */
+    uploadWorldFile(slug: string, worldFolderPath: string, worldId: string): Promise<void>;
     /**
      * Get the dashboard URL for the current environment.
      * @returns The dashboard URL.