@kradle/cli 0.2.7 → 0.2.8

package/README.md

@@ -9,6 +9,7 @@ Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
 * [Configuration](#configuration)
 * [Challenge](#challenge-commands)
 * [Experiments](#experiment-commands)
+* [Worlds](#world-commands)
 * [Agents](#agent-commands)
 * [AI Docs](#ai-docs-commands)
 * [Publishing a New Version](#publishing-a-new-version)
@@ -214,6 +215,61 @@ List all local experiments:
 kradle experiment list
 ```
 
+## World Commands
+
+Worlds are Minecraft world saves that can be used as starting points for challenges.
+
+### Import World
+
+Import a Minecraft world folder from your local filesystem:
+
+```bash
+kradle world import ~/minecraft/saves/MyWorld              # Auto-generate slug from folder name
+kradle world import ~/minecraft/saves/MyWorld --as my-world  # Specify custom slug
+```
+
+This validates the folder contains `level.dat`, packages it as a tarball, creates a `config.ts`, and uploads to the cloud.
+
+### Push World
+
+Upload world config and tarball to the cloud:
+
+```bash
+kradle world push my-world                     # Push single world
+kradle world push my-world another-world       # Push multiple worlds
+kradle world push --all                        # Push all local worlds
+```
+
+### Pull World
+
+Download a world from the cloud:
+
+```bash
+kradle world pull                              # Interactive selection
+kradle world pull my-world                     # Pull specific world
+kradle world pull username:their-world         # Pull from another user
+kradle world pull my-world --yes               # Skip confirmation when overwriting
+```
+
+### List Worlds
+
+List all worlds (local and cloud):
+
+```bash
+kradle world list
+```
+
+Shows sync status for each world (synced, cloud only, or local only).
+
+### Delete World
+
+Delete a world locally, from the cloud, or both:
+
+```bash
+kradle world delete my-world          # Interactive confirmation
+kradle world delete my-world --yes    # Skip confirmation
+```
+
 ## Agent Commands
 
 ### List Agents
@@ -347,14 +403,16 @@ kradle-cli/
 │   │   ├── agent/            # Agent commands
 │   │   ├── ai-docs/          # AI documentation commands
 │   │   ├── challenge/        # Challenge management commands
-│   │   └── experiment/       # Experiment commands
+│   │   ├── experiment/       # Experiment commands
+│   │   └── world/            # World management commands
 │   └── lib/                  # Core libraries
 │       └── experiment/       # Experiment system
 ├── tests/                    # Integration tests
 │   ├── helpers/              # Test utilities
 │   └── integration/          # Integration test suites
 │       ├── challenge/        # Challenge command tests
-│       └── experiment/       # Experiment command tests
+│       ├── experiment/       # Experiment command tests
+│       └── world/            # World command tests
 └── static/                   # Template files
     └── project_template/     # Files for kradle init
 ```

package/bin/run.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node --no-warnings
+#!/usr/bin/env -S node --no-warnings
 
 import { execute } from "@oclif/core";
 import path from "node:path";

package/dist/commands/world/push.d.ts

@@ -3,11 +3,13 @@ export default class Push extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        worldSlug: import("@oclif/core/interfaces").Arg<string>;
+        worldSlug: import("@oclif/core/interfaces").Arg<string | undefined>;
     };
     static flags: {
         "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>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    static strict: boolean;
     run(): Promise<void>;
 }

package/dist/commands/world/push.js

@@ -1,4 +1,4 @@
-import { Command } from "@oclif/core";
+import { Command, Flags, loadHelpClass } from "@oclif/core";
 import { Listr } from "listr2";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
@@ -7,58 +7,102 @@ import { getConfigFlags } from "../../lib/flags.js";
 import { World } from "../../lib/world.js";
 export default class Push extends Command {
     static description = "Upload a world (config + tarball) to the cloud";
-    static examples = ["<%= config.bin %> <%= command.id %> my-world"];
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-world",
+        "<%= config.bin %> <%= command.id %> my-world my-other-world",
+        "<%= config.bin %> <%= command.id %> --all",
+    ];
     static args = {
-        worldSlug: getWorldSlugArgument({ description: "World slug to push" }),
+        worldSlug: getWorldSlugArgument({
+            description: "World slug to push. Can be used multiple times to push multiple worlds at once. Incompatible with --all flag.",
+            required: false,
+        }),
     };
     static flags = {
+        all: Flags.boolean({ char: "a", description: "Push all worlds in the worlds directory", default: false }),
         ...getConfigFlags("api-key", "api-url"),
     };
+    static strict = false;
     async run() {
-        const { args, flags } = await this.parse(Push);
-        const world = new World(args.worldSlug);
-        if (!world.exists()) {
-            this.error(pc.red(`World "${args.worldSlug}" does not exist locally.`));
+        const { argv, flags } = await this.parse(Push);
+        if (flags.all && argv.length > 0) {
+            this.error(pc.red("Cannot use --all flag with world slugs"));
         }
-        if (!world.tarballExists()) {
-            this.error(pc.red(`World tarball not found at ${world.tarballPath}`));
+        if (!flags.all && argv.length === 0) {
+            await new (await loadHelpClass(this.config))(this.config).showHelp([Push.id]);
+            return;
         }
-        const isValid = await world.validateTarball();
-        if (!isValid) {
-            this.error(pc.red(`Invalid world tarball: level.dat not found in ${world.tarballPath}`));
+        if (flags.all) {
+            this.log(pc.blue("Pushing all worlds"));
         }
+        const worldSlugs = flags.all ? await World.getLocalWorlds() : argv;
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
-        const config = await world.loadConfig();
-        const tasks = new Listr([
-            {
-                title: "Ensuring world exists in cloud",
-                task: async (_ctx, task) => {
-                    const exists = await api.worldExists(args.worldSlug);
-                    if (!exists) {
-                        await api.createWorld(args.worldSlug, config);
-                        task.title = "Created world in cloud";
-                    }
-                    else {
-                        task.title = "World exists in cloud";
-                    }
+        const failedWorlds = [];
+        for (const worldSlug of worldSlugs) {
+            this.log(pc.blue(`==== Pushing world: ${worldSlug} ====`));
+            const world = new World(worldSlug);
+            if (!world.exists()) {
+                const reason = `World "${worldSlug}" does not exist locally`;
+                this.log(pc.red(`${reason}. Skipping.`));
+                this.log();
+                failedWorlds.push({ slug: worldSlug, reason });
+                continue;
+            }
+            if (!world.tarballExists()) {
+                const reason = `World tarball not found at ${world.tarballPath}`;
+                this.log(pc.red(`${reason}. Skipping.`));
+                this.log();
+                failedWorlds.push({ slug: worldSlug, reason });
+                continue;
+            }
+            const isValid = await world.validateTarball();
+            if (!isValid) {
+                const reason = `Invalid world tarball: level.dat not found in ${world.tarballPath}`;
+                this.log(pc.red(`${reason}. Skipping.`));
+                this.log();
+                failedWorlds.push({ slug: worldSlug, reason });
+                continue;
+            }
+            const config = await world.loadConfig();
+            const tasks = new Listr([
+                {
+                    title: "Ensuring world exists in cloud",
+                    task: async (_ctx, task) => {
+                        const exists = await api.worldExists(worldSlug);
+                        if (!exists) {
+                            await api.createWorld(worldSlug, config);
+                            task.title = "Created world in cloud";
+                        }
+                        else {
+                            task.title = "World exists in cloud";
+                        }
+                    },
                 },
-            },
-            {
-                title: "Uploading config",
-                task: async (_ctx, task) => {
-                    await api.updateWorld(args.worldSlug, config);
-                    task.title = "Config uploaded";
+                {
+                    title: "Uploading config",
+                    task: async (_ctx, task) => {
+                        await api.updateWorld(worldSlug, config);
+                        task.title = "Config uploaded";
+                    },
                 },
-            },
-            {
-                title: "Uploading world",
-                task: async (_ctx, task) => {
-                    await api.uploadWorldFile(args.worldSlug, world.tarballPath);
-                    task.title = "World uploaded";
+                {
+                    title: "Uploading world",
+                    task: async (_ctx, task) => {
+                        await api.uploadWorldFile(worldSlug, world.tarballPath);
+                        task.title = "World uploaded";
+                    },
                 },
-            },
-        ]);
-        await tasks.run();
-        this.log(pc.green(`\n✓ World pushed: ${args.worldSlug}`));
+            ]);
+            await tasks.run();
+            this.log(pc.green(`✓ World pushed: ${worldSlug}`));
+            this.log();
+        }
+        if (failedWorlds.length > 0) {
+            this.log(pc.red("\nFailed to push the following worlds:"));
+            for (const { slug, reason } of failedWorlds) {
+                this.log(pc.red(`  - ${slug}: ${reason}`));
+            }
+            this.error(pc.red(`\n${failedWorlds.length} world(s) failed to push`));
+        }
     }
 }

package/oclif.manifest.json

@@ -1092,16 +1092,25 @@
       "aliases": [],
       "args": {
         "worldSlug": {
-          "description": "World slug to push",
+          "description": "World slug to push. Can be used multiple times to push multiple worlds at once. Incompatible with --all flag.",
           "name": "worldSlug",
-          "required": true
+          "required": false
         }
       },
       "description": "Upload a world (config + tarball) to the cloud",
       "examples": [
-        "<%= config.bin %> <%= command.id %> my-world"
+        "<%= config.bin %> <%= command.id %> my-world",
+        "<%= config.bin %> <%= command.id %> my-world my-other-world",
+        "<%= config.bin %> <%= command.id %> --all"
       ],
       "flags": {
+        "all": {
+          "char": "a",
+          "description": "Push all worlds in the worlds directory",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "api-key": {
           "description": "Kradle API key",
           "env": "KRADLE_API_KEY",
@@ -1128,7 +1137,7 @@
       "pluginAlias": "@kradle/cli",
       "pluginName": "@kradle/cli",
       "pluginType": "core",
-      "strict": true,
+      "strict": false,
       "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
@@ -1139,5 +1148,5 @@
       ]
     }
   },
-  "version": "0.2.7"
+  "version": "0.2.8"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kradle/cli",
-	"version": "0.2.7",
+	"version": "0.2.8",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -9,6 +9,7 @@ This document provides exhaustive documentation for LLM agents using the Kradle
 - [Project Initialization](#project-initialization)
 - [Challenge Commands](#challenge-commands)
 - [Experiment Commands](#experiment-commands)
+- [World Commands](#world-commands)
 - [Agent Commands](#agent-commands)
 - [AI Docs Commands](#ai-docs-commands)
 - [Common Workflows](#common-workflows)
@@ -559,6 +560,208 @@ kradle experiment list
 
 ---
 
+## World Commands
+
+Worlds are Minecraft world saves that can be used as starting points for challenges.
+
+### `kradle world import <path>`
+
+Imports a Minecraft world folder from your local filesystem and packages it for use with Kradle.
+
+**Usage:**
+```bash
+kradle world import ~/minecraft/saves/MyWorld
+kradle world import ~/minecraft/saves/MyWorld --as my-world
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `path` | Path to the Minecraft world folder (must contain `level.dat`) | Yes |
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--as` | Slug for the world (defaults to folder name converted to slug) | Auto-generated |
+
+**What it does:**
+1. Validates the folder contains `level.dat`
+2. Creates `worlds/<slug>/` directory
+3. Packages world as `world.tar.gz`
+4. Creates `config.ts` with default metadata
+5. Uploads to cloud
+
+**Re-importing:** If the world already exists locally, re-import updates the tarball while preserving `config.ts`.
+
+**Examples:**
+```bash
+# Import with auto-generated slug
+kradle world import ~/minecraft/saves/MyWorld
+
+# Import with custom slug
+kradle world import ~/minecraft/saves/MyWorld --as custom-world
+```
+
+---
+
+### `kradle world push <slug...>`
+
+Uploads world config and tarball to the cloud.
+
+**Usage:**
+```bash
+kradle world push <world-slug>
+kradle world push <world-slug> <another-world>
+kradle world push --all
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `world-slug` | World slug(s) to push. Can specify multiple slugs. | Yes (unless `--all`) |
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--all` | `-a` | Push all worlds in the worlds directory | false |
+
+**What it does:**
+1. Creates the world in cloud if it doesn't exist
+2. Uploads `config.ts` metadata
+3. Uploads `world.tar.gz` tarball
+
+**Examples:**
+```bash
+# Push single world
+kradle world push my-world
+
+# Push multiple worlds
+kradle world push my-world another-world
+
+# Push all local worlds
+kradle world push --all
+```
+
+---
+
+### `kradle world pull [slug]`
+
+Downloads a world from the cloud.
+
+**Usage:**
+```bash
+kradle world pull
+kradle world pull <world-slug>
+kradle world pull <username>:<world-slug>
+kradle world pull <world-slug> --yes
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `world-slug` | World slug to pull. If omitted, shows interactive selection. | No |
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--yes` | `-y` | Skip confirmation prompts when overwriting local files | false |
+
+**Interactive mode (no slug argument):**
+- Shows list of all cloud worlds (your own + team-kradle)
+- Marks worlds that exist locally with "(local)" indicator
+- Select a world to pull
+
+**What it does:**
+1. Downloads `world.tar.gz` from cloud
+2. Creates `config.ts` from cloud metadata
+3. Places files in `worlds/<short-slug>/` directory
+
+**Examples:**
+```bash
+# Interactive selection
+kradle world pull
+
+# Pull specific world
+kradle world pull my-world
+
+# Pull from another user
+kradle world pull username:their-world
+
+# Pull without confirmation
+kradle world pull my-world --yes
+```
+
+---
+
+### `kradle world list`
+
+Lists all worlds (local and cloud).
+
+**Usage:**
+```bash
+kradle world list
+```
+
+**Output format:**
+```
+Worlds:
+
+Status          Slug                                     Name
+------------------------------------------------------------------------------------------
+✓ synced        username:my-world                        My World
+☁ cloud only    username:cloud-world                     Cloud World
+⊡ local only    username:local-world                     -
+
+Total: 3 worlds
+```
+
+**Status indicators:**
+- `✓ synced` - Exists both locally and in cloud
+- `☁ cloud only` - Only in cloud, not local
+- `⊡ local only` - Only local, not in cloud
+
+**Example:**
+```bash
+kradle world list
+```
+
+---
+
+### `kradle world delete <slug>`
+
+Deletes a world locally, from the cloud, or both.
+
+**Usage:**
+```bash
+kradle world delete <world-slug>
+kradle world delete <world-slug> --yes
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `world-slug` | World slug to delete | Yes |
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--yes` | `-y` | Skip confirmation prompts | false |
+
+**Interactive prompts (unless `--yes`):**
+1. Delete local files? (y/n)
+2. Delete from cloud? (y/n)
+
+**Examples:**
+```bash
+# Interactive deletion
+kradle world delete my-world
+
+# Force delete without prompts
+kradle world delete my-world --yes
+```
+
+---
+
 ## Agent Commands
 
 ### `kradle agent list`
@@ -725,6 +928,12 @@ kradle challenge build --all --visibility public
 | `kradle experiment run <name>` | Run/resume experiment |
 | `kradle experiment recordings <name>` | Download recordings |
 | `kradle experiment list` | List experiments |
+| `kradle world import <path>` | Import Minecraft world folder |
+| `kradle world push <slug...>` | Push world(s) to cloud |
+| `kradle world push --all` | Push all worlds |
+| `kradle world pull [slug]` | Pull world from cloud |
+| `kradle world list` | List all worlds |
+| `kradle world delete <slug>` | Delete world |
 | `kradle agent list` | List available agents |
 | `kradle ai-docs cli` | Output CLI reference for LLMs |
 | `kradle ai-docs api` | Output API reference for LLMs |