@kradle/cli 0.2.4 → 0.2.6

package/README.md

@@ -111,6 +111,19 @@ List all challenges (local and cloud):
 kradle challenge list
 ```
 
+### Pull Challenge
+
+Download a challenge from the cloud and extract source files locally:
+
+```bash
+kradle challenge pull                                  # Interactive selection
+kradle challenge pull <challenge-name>                 # Pull your own challenge
+kradle challenge pull <team-name>:<challenge-name>     # Pull a public challenge from another team
+kradle challenge pull <challenge-name> --yes           # Skip confirmation when overwriting
+```
+
+This downloads the challenge tarball, extracts `challenge.ts` and `config.ts`, and builds the datapack locally.
+
 ### Watch Challenge
 
 Watch a challenge for changes and auto-rebuild/upload:

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

@@ -0,0 +1,15 @@
+import { Command } from "@oclif/core";
+export default class Pull extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        challengeSlug: 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>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/pull.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import * as tar from "tar";
+import { ApiClient } from "../../lib/api-client.js";
+import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
+import { getConfigFlags } from "../../lib/flags.js";
+export default class Pull extends Command {
+    static description = "Pull a challenge from the cloud and extract source files locally";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> username:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes",
+    ];
+    static args = {
+        challengeSlug: getChallengeSlugArgument({
+            description: "Challenge slug to pull (interactive selection if omitted)",
+            required: false,
+            allowTeam: true,
+        }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Pull);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        let challengeSlug = args.challengeSlug;
+        if (!challengeSlug) {
+            const [kradleChallenges, cloudChallenges, localChallenges] = await Promise.all([
+                api.listKradleChallenges(),
+                api.listChallenges(),
+                Challenge.getLocalChallenges(),
+            ]);
+            const allChallenges = [...kradleChallenges, ...cloudChallenges];
+            if (allChallenges.length === 0) {
+                this.error(pc.red("No challenges found in the cloud."));
+            }
+            const localSet = new Set(localChallenges);
+            const slugs = allChallenges.map((c) => c.slug).sort();
+            const choices = slugs.map((slug) => {
+                const shortSlug = extractShortSlug(slug);
+                const isLocal = localSet.has(shortSlug);
+                const status = isLocal ? pc.yellow(" (local)") : "";
+                return {
+                    name: slug,
+                    message: `${slug}${status}`,
+                };
+            });
+            const response = await enquirer.prompt({
+                type: "select",
+                name: "challenge",
+                message: "Select a challenge to pull",
+                choices,
+            });
+            challengeSlug = response.challenge;
+        }
+        const shortSlug = extractShortSlug(challengeSlug);
+        const challenge = new Challenge(shortSlug, flags["challenges-path"]);
+        const existsInCloud = await api.challengeExists(challengeSlug);
+        if (!existsInCloud) {
+            this.error(pc.red(`Challenge "${challengeSlug}" does not exist in the cloud.`));
+        }
+        const existsLocally = existsSync(challenge.challengeDir);
+        const hasLocalFiles = existsLocally && (existsSync(challenge.challengePath) || existsSync(challenge.configPath));
+        if (hasLocalFiles && !flags.yes) {
+            this.log(pc.bold(`\nChallenge: ${pc.cyan(challenge.shortSlug)}`));
+            this.log(`  Local folder exists: ${pc.yellow(challenge.challengeDir)}`);
+            if (existsSync(challenge.challengePath)) {
+                this.log(`  challenge.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            if (existsSync(challenge.configPath)) {
+                this.log(`  config.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            this.log("");
+            try {
+                const response = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Overwrite local challenge files? ${pc.red("This cannot be undone.")}`,
+                    initial: false,
+                });
+                if (!response.confirm) {
+                    this.log(pc.yellow("Pull cancelled"));
+                    return;
+                }
+            }
+            catch {
+                this.log(pc.yellow("\nPull cancelled"));
+                return;
+            }
+        }
+        const tempTarballPath = path.join(flags["challenges-path"], `${challenge.shortSlug}-pull-temp.tar.gz`);
+        const tasks = new Listr([
+            {
+                title: "Downloading challenge",
+                task: async (_, task) => {
+                    const { downloadUrl } = await api.getChallengeDownloadUrl(challengeSlug);
+                    const response = await fetch(downloadUrl);
+                    if (!response.ok) {
+                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+                    }
+                    const buffer = await response.arrayBuffer();
+                    await fs.mkdir(path.dirname(tempTarballPath), { recursive: true });
+                    await fs.writeFile(tempTarballPath, Buffer.from(buffer));
+                    task.title = "Downloaded challenge";
+                },
+            },
+            {
+                title: "Creating challenge directory",
+                task: async (_, task) => {
+                    await fs.mkdir(challenge.challengeDir, { recursive: true });
+                    task.title = `Created directory: ${challenge.challengeDir}`;
+                },
+            },
+            {
+                title: "Extracting source files",
+                task: async (_, task) => {
+                    const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
+                    const tempExtractDir = path.join(flags["challenges-path"], `${challenge.shortSlug}-extract-temp`);
+                    await fs.mkdir(tempExtractDir, { recursive: true });
+                    try {
+                        await tar.extract({
+                            file: tempTarballPath,
+                            cwd: tempExtractDir,
+                            filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
+                        });
+                        const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
+                        const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
+                        let extractedCount = 0;
+                        if (existsSync(srcChallengeTs)) {
+                            await fs.copyFile(srcChallengeTs, challenge.challengePath);
+                            extractedCount++;
+                        }
+                        if (existsSync(srcConfigTs)) {
+                            await fs.copyFile(srcConfigTs, challenge.configPath);
+                            extractedCount++;
+                        }
+                        if (extractedCount === 0) {
+                            throw new Error(`No source files found in tarball. The challenge may not have been built with source files.`);
+                        }
+                        task.title = `Extracted ${extractedCount} source file(s)`;
+                    }
+                    finally {
+                        await fs.rm(tempExtractDir, { recursive: true, force: true });
+                    }
+                },
+            },
+            {
+                title: "Cleaning up",
+                task: async (_, task) => {
+                    await fs.rm(tempTarballPath, { force: true });
+                    task.title = "Cleaned up temporary files";
+                },
+            },
+            {
+                title: "Building datapack",
+                task: async (_, task) => {
+                    await challenge.build(true);
+                    task.title = "Built datapack";
+                },
+            },
+        ]);
+        try {
+            await tasks.run();
+            this.log(pc.green(`\n✓ Challenge pulled: ${challenge.shortSlug}`));
+            this.log(pc.dim(`  → challenge.ts: ${challenge.challengePath}`));
+            this.log(pc.dim(`  → config.ts: ${challenge.configPath}`));
+        }
+        catch (error) {
+            await fs.rm(tempTarballPath, { force: true }).catch(() => { });
+            this.error(pc.red(`Pull failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

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

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

package/dist/commands/world/delete.js

@@ -0,0 +1,80 @@
+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 { getWorldSlugArgument } from "../../lib/arguments.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { World } from "../../lib/world.js";
+export default class Delete extends Command {
+    static description = "Delete a world locally, from the cloud, or both";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-world",
+        "<%= config.bin %> <%= command.id %> my-world --yes",
+    ];
+    static args = {
+        worldSlug: getWorldSlugArgument({ description: "World slug to delete" }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Delete);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const world = new World(args.worldSlug);
+        const existsLocally = world.exists();
+        const existsInCloud = await api.worldExists(args.worldSlug);
+        if (!existsLocally && !existsInCloud) {
+            this.error(pc.red(`World "${args.worldSlug}" does not exist locally or in the cloud.`));
+        }
+        this.log(pc.bold(`\nWorld: ${pc.cyan(args.worldSlug)}`));
+        if (existsLocally) {
+            this.log(`  📁 Local: ${pc.green("exists")} at ${world.worldDir}`);
+        }
+        else {
+            this.log(`  📁 Local: ${pc.dim("not found")}`);
+        }
+        if (existsInCloud) {
+            this.log(`  ☁  Cloud: ${pc.green("exists")}`);
+        }
+        else {
+            this.log(`  ☁  Cloud: ${pc.dim("not found")}`);
+        }
+        this.log("");
+        let deleteLocal = existsLocally;
+        let deleteCloud = existsInCloud;
+        if (!flags.yes) {
+            if (existsLocally) {
+                const response = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Delete local world files? ${pc.red("This cannot be undone.")}`,
+                    initial: true,
+                });
+                deleteLocal = response.confirm;
+            }
+            if (existsInCloud) {
+                const response = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Delete world from cloud? ${pc.red("This cannot be undone.")}`,
+                    initial: true,
+                });
+                deleteCloud = response.confirm;
+            }
+        }
+        if (!deleteLocal && !deleteCloud) {
+            this.log(pc.yellow("✗ Nothing deleted"));
+            return;
+        }
+        if (deleteLocal) {
+            await fs.rm(world.worldDir, { recursive: true, force: true });
+            this.log(pc.green(`✓ Deleted local: ${world.worldDir}`));
+        }
+        if (deleteCloud) {
+            await api.deleteWorld(args.worldSlug);
+            this.log(pc.green(`✓ Deleted from cloud: ${args.worldSlug}`));
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+import { Command } from "@oclif/core";
+export default class Import extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    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>;
+        as: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/world/import.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { Args, Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { World } from "../../lib/world.js";
+export default class Import extends Command {
+    static description = "Import a Minecraft world folder and package it as a tarball";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> ~/minecraft/saves/MyWorld",
+        "<%= config.bin %> <%= command.id %> ~/minecraft/saves/MyWorld --as my-world",
+    ];
+    static args = {
+        path: Args.string({
+            description: "Path to the Minecraft world folder",
+            required: true,
+        }),
+    };
+    static flags = {
+        as: Flags.string({
+            description: "Slug for the world (defaults to folder name converted to slug)",
+        }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Import);
+        const sourcePath = path.resolve(args.path);
+        if (!existsSync(sourcePath)) {
+            this.error(pc.red(`Source path does not exist: ${sourcePath}`));
+        }
+        const levelDatPath = path.join(sourcePath, "level.dat");
+        if (!existsSync(levelDatPath)) {
+            this.error(pc.red(`Invalid Minecraft world: level.dat not found in ${sourcePath}`));
+        }
+        let slug = flags.as;
+        if (!slug) {
+            const folderName = path.basename(sourcePath);
+            const suggestedSlug = World.toSlug(folderName);
+            const response = await enquirer.prompt({
+                type: "input",
+                name: "slug",
+                message: "World slug:",
+                initial: suggestedSlug,
+                validate: (input) => {
+                    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input)) {
+                        return "Slug must be lowercase alphanumeric with hyphens, not starting/ending with hyphen";
+                    }
+                    return true;
+                },
+            });
+            slug = response.slug;
+        }
+        const world = new World(slug);
+        const isReimport = world.exists();
+        if (isReimport) {
+            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"]);
+        const tasks = new Listr([
+            {
+                title: "Creating world directory",
+                enabled: () => !isReimport,
+                task: async (_ctx, task) => {
+                    const config = {
+                        name: slug,
+                        description: "no description",
+                        visibility: "private",
+                        domain: "minecraft",
+                    };
+                    await World.createLocal(slug, config);
+                    task.title = `Created worlds/${slug}/`;
+                },
+            },
+            {
+                title: isReimport ? "Updating tarball" : "Packaging world as tarball",
+                task: async (_ctx, task) => {
+                    await World.createTarballFrom(sourcePath, slug);
+                    task.title = isReimport ? `Updated worlds/${slug}/world.tar.gz` : `Created worlds/${slug}/world.tar.gz`;
+                },
+            },
+            {
+                title: "Creating world in cloud",
+                enabled: () => !isReimport,
+                task: async (_ctx, task) => {
+                    const exists = await api.worldExists(slug);
+                    if (exists) {
+                        task.title = "World already exists in cloud";
+                        return;
+                    }
+                    const config = {
+                        name: slug,
+                        visibility: "private",
+                        domain: "minecraft",
+                    };
+                    await api.createWorld(slug, config);
+                    task.title = "Created world in cloud";
+                },
+            },
+        ]);
+        await tasks.run();
+        if (isReimport) {
+            this.log(pc.green(`\n✓ World re-imported: ${slug}`));
+            this.log(pc.dim(`  → world.tar.gz updated (config.ts preserved)`));
+            this.log(pc.dim(`\nRun ${pc.cyan(`kradle world push ${slug}`)} to upload to cloud.`));
+        }
+        else {
+            this.log(pc.green(`\n✓ World imported: ${slug}`));
+            this.log(pc.dim(`  → config.ts: ${world.configPath}`));
+            this.log(pc.dim(`  → world.tar.gz: ${world.tarballPath}`));
+            this.log(pc.dim(`\nRun ${pc.cyan(`kradle world push ${slug}`)} to upload to cloud.`));
+        }
+    }
+}

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

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

package/dist/commands/world/list.js

@@ -0,0 +1,46 @@
+import { Command } from "@oclif/core";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { World } from "../../lib/world.js";
+export default class List extends Command {
+    static description = "List all worlds (local and cloud)";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    static flags = {
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { flags } = await this.parse(List);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        this.log(pc.blue(">> Loading worlds..."));
+        const [cloudWorlds, localWorlds, human] = await Promise.all([
+            api.listWorlds(),
+            World.getLocalWorlds(),
+            api.getHuman(),
+        ]);
+        const cloudMap = new Map(cloudWorlds.map((w) => [w.slug, w]));
+        const allSlugs = new Set([...cloudMap.keys(), ...localWorlds.map((slug) => `${human.username}:${slug}`)]);
+        this.log(pc.bold("\nWorlds:\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 inCloud = cloudMap.has(slug);
+            const shortSlug = slug.includes(":") ? slug.split(":")[1] : slug;
+            const inLocal = localWorlds.includes(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 cloudWorld = cloudMap.get(slug);
+            const name = cloudWorld?.name || "-";
+            this.log(`${status.padEnd(24)} ${slug.padEnd(40)} ${name.padEnd(30)}`);
+        }
+        this.log(pc.dim(`\nTotal: ${allSlugs.size} worlds`));
+    }
+}

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

@@ -0,0 +1,14 @@
+import { Command } from "@oclif/core";
+export default class Pull extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        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>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/world/pull.js

@@ -0,0 +1,135 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { extractShortSlug, getWorldSlugArgument } from "../../lib/arguments.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { World } from "../../lib/world.js";
+export default class Pull extends Command {
+    static description = "Download a world from the cloud";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-world",
+        "<%= config.bin %> <%= command.id %> username:my-world",
+        "<%= config.bin %> <%= command.id %> my-world --yes",
+    ];
+    static args = {
+        worldSlug: getWorldSlugArgument({
+            description: "World slug to pull (interactive selection if omitted)",
+            required: false,
+            allowTeam: true,
+        }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Pull);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        let worldSlug = args.worldSlug;
+        if (!worldSlug) {
+            const [kradleWorlds, cloudWorlds, localWorlds] = await Promise.all([
+                api.listKradleWorlds(),
+                api.listWorlds(),
+                World.getLocalWorlds(),
+            ]);
+            const allWorlds = [...kradleWorlds, ...cloudWorlds];
+            if (allWorlds.length === 0) {
+                this.error(pc.red("No worlds found in the cloud."));
+            }
+            const localSet = new Set(localWorlds);
+            const choices = allWorlds
+                .map((w) => w.slug)
+                .toSorted()
+                .map((slug) => {
+                const shortSlug = extractShortSlug(slug);
+                const isLocal = localSet.has(shortSlug);
+                const status = isLocal ? pc.yellow(" (local)") : "";
+                return {
+                    name: slug,
+                    message: `${slug}${status}`,
+                };
+            });
+            const response = await enquirer.prompt({
+                type: "select",
+                name: "world",
+                message: "Select a world to pull",
+                choices,
+            });
+            worldSlug = response.world;
+        }
+        const shortSlug = extractShortSlug(worldSlug);
+        const world = new World(shortSlug);
+        const existsInCloud = await api.worldExists(worldSlug);
+        if (!existsInCloud) {
+            this.error(pc.red(`World "${worldSlug}" does not exist in the cloud.`));
+        }
+        const existsLocally = world.exists();
+        if (existsLocally && !flags.yes) {
+            this.log(pc.bold(`\nWorld: ${pc.cyan(worldSlug)}`));
+            this.log(`  📁 Local folder exists: ${pc.yellow(world.worldDir)}`);
+            if (world.tarballExists()) {
+                this.log(`  📦 world.tar.gz: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            if (existsSync(world.configPath)) {
+                this.log(`  📄 config.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            this.log("");
+            const confirmResponse = await enquirer.prompt({
+                type: "confirm",
+                name: "confirm",
+                message: `Overwrite local world files? ${pc.red("This cannot be undone.")}`,
+                initial: false,
+            });
+            if (!confirmResponse.confirm) {
+                this.log(pc.yellow("✗ Pull cancelled"));
+                return;
+            }
+        }
+        const cloudWorld = await api.getWorld(worldSlug);
+        const tasks = new Listr([
+            {
+                title: "Creating world directory",
+                task: async () => {
+                    await fs.mkdir(world.worldDir, { recursive: true });
+                },
+            },
+            {
+                title: "Downloading world",
+                task: async (_ctx, task) => {
+                    const { downloadUrl } = await api.getWorldDownloadUrl(worldSlug);
+                    const response = await fetch(downloadUrl);
+                    if (!response.ok) {
+                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+                    }
+                    const buffer = await response.arrayBuffer();
+                    await fs.writeFile(world.tarballPath, Buffer.from(buffer));
+                    task.title = "Downloaded world";
+                },
+            },
+            {
+                title: "Creating config.ts",
+                task: async (_ctx, task) => {
+                    const config = {
+                        name: cloudWorld.name,
+                        description: cloudWorld.description ?? "no description",
+                        visibility: cloudWorld.visibility,
+                        domain: "minecraft",
+                    };
+                    const configContent = `export const config = ${JSON.stringify(config, null, "\t").replace(/"([a-zA-Z_][a-zA-Z0-9_]*)"\s*:/g, "$1:")};
+`;
+                    await fs.writeFile(world.configPath, configContent);
+                    task.title = "Created config.ts";
+                },
+            },
+        ]);
+        await tasks.run();
+        this.log(pc.green(`\n✓ World pulled: ${worldSlug}`));
+        this.log(pc.dim(`  → config.ts: ${world.configPath}`));
+        this.log(pc.dim(`  → world.tar.gz: ${world.tarballPath}`));
+    }
+}

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

@@ -0,0 +1,13 @@
+import { Command } from "@oclif/core";
+export default class Push extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        worldSlug: import("@oclif/core/interfaces").Arg<string>;
+    };
+    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>;
+    };
+    run(): Promise<void>;
+}