@kradle/cli 0.2.4 → 0.2.6

package/dist/commands/world/push.js

@@ -0,0 +1,64 @@
+import { Command } from "@oclif/core";
+import { Listr } from "listr2";
+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 Push extends Command {
+    static description = "Upload a world (config + tarball) to the cloud";
+    static examples = ["<%= config.bin %> <%= command.id %> my-world"];
+    static args = {
+        worldSlug: getWorldSlugArgument({ description: "World slug to push" }),
+    };
+    static flags = {
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    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.`));
+        }
+        if (!world.tarballExists()) {
+            this.error(pc.red(`World tarball not found at ${world.tarballPath}`));
+        }
+        const isValid = await world.validateTarball();
+        if (!isValid) {
+            this.error(pc.red(`Invalid world tarball: level.dat not found in ${world.tarballPath}`));
+        }
+        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";
+                    }
+                },
+            },
+            {
+                title: "Uploading config",
+                task: async (_ctx, task) => {
+                    await api.updateWorld(args.worldSlug, config);
+                    task.title = "Config uploaded";
+                },
+            },
+            {
+                title: "Uploading world",
+                task: async (_ctx, task) => {
+                    await api.uploadWorldFile(args.worldSlug, world.tarballPath);
+                    task.title = "World uploaded";
+                },
+            },
+        ]);
+        await tasks.run();
+        this.log(pc.green(`\n✓ World pushed: ${args.worldSlug}`));
+    }
+}

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

@@ -1,5 +1,5 @@
 import type z from "zod";
-import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, HumanSchema, type RecordingDownloadUrlResponse, type RecordingMetadata, type RunStatusSchemaType } from "./schemas.js";
+import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DownloadUrlResponse, HumanSchema, type RecordingMetadata, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
 export declare class ApiClient {
     private apiUrl;
     private kradleApiKey;
@@ -66,6 +66,7 @@ export declare class ApiClient {
      * @returns The upload URL.
      */
     getChallengeUploadUrl(slug: string): Promise<string>;
+    getChallengeDownloadUrl(slug: string): Promise<DownloadUrlResponse>;
     runChallenge(runData: {
         challenge: string;
         participants: unknown[];
@@ -106,5 +107,15 @@ export declare class ApiClient {
      * @param timestamp - The timestamp of the recording.
      * @returns Download URL and expiration time.
      */
-    getRecordingDownloadUrl(runId: string, participantId: string, timestamp: string): Promise<RecordingDownloadUrlResponse>;
+    getRecordingDownloadUrl(runId: string, participantId: string, timestamp: string): Promise<DownloadUrlResponse>;
+    listWorlds(): Promise<WorldSchemaType[]>;
+    listKradleWorlds(): Promise<WorldSchemaType[]>;
+    getWorld(slug: string): Promise<WorldSchemaType>;
+    worldExists(slug: string): Promise<boolean>;
+    createWorld(slug: string, config: WorldConfigSchemaType): Promise<WorldSchemaType>;
+    updateWorld(slug: string, config: WorldConfigSchemaType): Promise<void>;
+    deleteWorld(slug: string): Promise<void>;
+    getWorldUploadUrl(slug: string): Promise<string>;
+    getWorldDownloadUrl(slug: string): Promise<DownloadUrlResponse>;
+    uploadWorldFile(slug: string, tarballPath: string): Promise<void>;
 }

package/dist/lib/api-client.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, HumanSchema, JobResponseSchema, RecordingDownloadUrlResponseSchema, RecordingsListResponseSchema, RunStatusSchema, UploadUrlResponseSchema, } from "./schemas.js";
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
 const DEFAULT_PAGE_SIZE = 30;
 const DEFAULT_CHALLENGE_SCHEMA = {
     slug: "",
@@ -210,6 +210,9 @@ export class ApiClient {
         const response = await this.get(`challenges/${slug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
         return response.uploadUrl;
     }
+    async getChallengeDownloadUrl(slug) {
+        return this.get(`challenges/${slug}/datapackDownloadUrl`, {}, DownloadUrlResponseSchema);
+    }
     async runChallenge(runData) {
         const url = "jobs";
         const payload = this.isStudio ? runData : { ...runData, jobType: "background" };
@@ -262,6 +265,60 @@ export class ApiClient {
      */
     async getRecordingDownloadUrl(runId, participantId, timestamp) {
         const url = `runs/${runId}/recordings/${participantId}/downloadUrl?timestamp=${encodeURIComponent(timestamp)}`;
-        return this.get(url, {}, RecordingDownloadUrlResponseSchema);
+        return this.get(url, {}, DownloadUrlResponseSchema);
+    }
+    async listWorlds() {
+        return this.listResource("worlds", "worlds", WorldsResponseSchema);
+    }
+    async listKradleWorlds() {
+        return this.listResource("humans/team-kradle/worlds", "worlds", WorldsResponseSchema);
+    }
+    async getWorld(slug) {
+        return this.get(`worlds/${slug}`, {}, WorldSchema);
+    }
+    async worldExists(slug) {
+        try {
+            const res = await this.get(`worlds/${slug}`, {});
+            return res !== null && res !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    async createWorld(slug, config) {
+        return this.post("worlds", { body: JSON.stringify({ slug, ...config }) }, WorldSchema);
+    }
+    async updateWorld(slug, config) {
+        await this.put(`worlds/${slug}`, {
+            body: JSON.stringify({ slug, ...config }),
+        });
+    }
+    async deleteWorld(slug) {
+        await this.delete(`worlds/${slug}`);
+    }
+    async getWorldUploadUrl(slug) {
+        const response = await this.get(`worlds/${slug}/uploadUrl`, {}, UploadUrlResponseSchema);
+        return response.uploadUrl;
+    }
+    async getWorldDownloadUrl(slug) {
+        return this.get(`worlds/${slug}/downloadUrl`, {}, DownloadUrlResponseSchema);
+    }
+    async uploadWorldFile(slug, tarballPath) {
+        const uploadUrl = await this.getWorldUploadUrl(slug);
+        if (!existsSync(tarballPath)) {
+            throw new Error(`World tarball not found at ${tarballPath}`);
+        }
+        const fileBuffer = await fs.readFile(tarballPath);
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/gzip",
+                "Content-Length": fileBuffer.length.toString(),
+            },
+            body: fileBuffer,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to upload world: ${response.statusText}`);
+        }
     }
 }

package/dist/lib/arguments.d.ts

@@ -1,12 +1,12 @@
 import type { Arg } from "@oclif/core/interfaces";
-/**
- * Returns a "challenge slug" argument, validating it to be a valid challenge slug.
- * @param description - Description for the argument
- * @param required - Whether the argument is required (default: true)
- * @param allowTeam - Whether to allow namespaced slugs like "team-name:my-challenge" (default: false)
- */
+export declare function extractShortSlug(slug: string): string;
 export declare function getChallengeSlugArgument<R extends boolean = true>({ description, required, allowTeam, }: {
     description: string;
     required?: R;
     allowTeam?: boolean;
 }): Arg<R extends true ? string : string | undefined>;
+export declare function getWorldSlugArgument<R extends boolean = true>({ description, required, allowTeam, }: {
+    description: string;
+    required?: R;
+    allowTeam?: boolean;
+}): Arg<R extends true ? string : string | undefined>;

package/dist/lib/arguments.js

@@ -1,16 +1,13 @@
 import { Args } from "@oclif/core";
-// Base pattern for a slug segment (lowercase alphanumeric with hyphens, no leading/trailing hyphens)
 const SLUG_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
-// Local challenge slug pattern: just the challenge name (no namespace)
 const LOCAL_SLUG_REGEX = new RegExp(`^${SLUG_SEGMENT}$`);
-// Full challenge slug pattern: optional namespace prefix (e.g., "team-name:") followed by the challenge slug
 const NAMESPACED_SLUG_REGEX = new RegExp(`^(?:${SLUG_SEGMENT}:)?${SLUG_SEGMENT}$`);
-/**
- * Returns a "challenge slug" argument, validating it to be a valid challenge slug.
- * @param description - Description for the argument
- * @param required - Whether the argument is required (default: true)
- * @param allowTeam - Whether to allow namespaced slugs like "team-name:my-challenge" (default: false)
- */
+export function extractShortSlug(slug) {
+    if (slug.includes(":")) {
+        return slug.split(":")[1];
+    }
+    return slug;
+}
 export function getChallengeSlugArgument({ description, required, allowTeam = false, }) {
     const regex = allowTeam ? NAMESPACED_SLUG_REGEX : LOCAL_SLUG_REGEX;
     const errorMessage = allowTeam
@@ -29,3 +26,21 @@ export function getChallengeSlugArgument({ description, required, allowTeam = fa
     // biome-ignore lint/suspicious/noExplicitAny: Typescript can't handle the conditional "required"
     return arg;
 }
+export function getWorldSlugArgument({ description, required, allowTeam = false, }) {
+    const regex = allowTeam ? NAMESPACED_SLUG_REGEX : LOCAL_SLUG_REGEX;
+    const errorMessage = allowTeam
+        ? "World slugs must be lowercase alphanumeric characters and hyphens, and must not start or end with a hyphen. Optionally, a team prefix can be provided (e.g., 'team-name:my-world')."
+        : "World slugs must be lowercase alphanumeric characters and hyphens, and must not start or end with a hyphen.";
+    const arg = Args.string({
+        description,
+        required: required ?? true,
+        parse: async (input) => {
+            if (!regex.test(input)) {
+                throw new Error(`Invalid world slug: ${input}. ${errorMessage}`);
+            }
+            return input;
+        },
+    });
+    // biome-ignore lint/suspicious/noExplicitAny: Typescript can't handle the conditional "required"
+    return arg;
+}

package/dist/lib/challenge.d.ts

@@ -37,9 +37,6 @@ export declare class Challenge {
      * Build the challenge datapack
      */
     build(silent?: boolean): Promise<void>;
-    /**
-     * Load the challenge configuration from config.ts
-     */
     loadConfig(): Promise<ChallengeConfigSchemaType>;
     /**
      * Build the challenge datapack and upload it to the cloud.

package/dist/lib/challenge.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import pc from "picocolors";
 import * as tar from "tar";
 import { ChallengeConfigSchema } from "./schemas.js";
-import { executeNodeCommand, executeTypescriptFile, getStaticResourcePath, readDirSorted } from "./utils.js";
+import { executeTypescriptFile, getStaticResourcePath, loadTypescriptExport, readDirSorted } from "./utils.js";
 export const SOURCE_FOLDER = ".src";
 export class Challenge {
     shortSlug;
@@ -106,25 +106,15 @@ export class Challenge {
             strict: true,
         }, ["datapack", SOURCE_FOLDER]);
     }
-    /**
-     * Load the challenge configuration from config.ts
-     */
     async loadConfig() {
         if (!existsSync(this.configPath)) {
             throw new Error(`Config file not found at ${this.configPath}`);
         }
-        // We spawn a new NodeJS process to execute & log the config file.
-        // We can't directly import the file because it would be cached, and import cache can't be invalidated.
-        const stdout = await executeNodeCommand([
-            "--experimental-transform-types",
-            "--no-warnings",
-            "-e",
-            `console.log(JSON.stringify(require("${this.configPath}").config));`,
-        ], {
+        const config = await loadTypescriptExport(this.configPath, "config", {
             KRADLE_CHALLENGES_PATH: this.kradleChallengesPath,
             NAMESPACE: "kradle",
         });
-        return ChallengeConfigSchema.parse(JSON.parse(stdout));
+        return ChallengeConfigSchema.parse(config);
     }
     /**
      * Build the challenge datapack and upload it to the cloud.

package/dist/lib/schemas.d.ts

@@ -143,6 +143,10 @@ export declare const UploadUrlResponseSchema: z.ZodObject<{
     uploadUrl: z.ZodString;
     expiresAt: z.ZodString;
 }, z.core.$strip>;
+export declare const DownloadUrlResponseSchema: z.ZodObject<{
+    downloadUrl: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
 export declare const AgentSchema: z.ZodObject<{
     username: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
@@ -186,9 +190,44 @@ export declare const RecordingsListResponseSchema: z.ZodObject<{
         sizeBytes: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const RecordingDownloadUrlResponseSchema: z.ZodObject<{
-    downloadUrl: z.ZodString;
-    expiresAt: z.ZodString;
+export declare const WorldSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    visibility: z.ZodEnum<{
+        private: "private";
+        public: "public";
+    }>;
+    creationTime: z.ZodString;
+    updateTime: z.ZodString;
+    creator: z.ZodString;
+}, z.core.$strip>;
+export declare const WorldConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodEnum<{
+        private: "private";
+        public: "public";
+    }>;
+    domain: z.ZodDefault<z.ZodLiteral<"minecraft">>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const WorldsResponseSchema: z.ZodObject<{
+    worlds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        visibility: z.ZodEnum<{
+            private: "private";
+            public: "public";
+        }>;
+        creationTime: z.ZodString;
+        updateTime: z.ZodString;
+        creator: z.ZodString;
+    }, z.core.$strip>>;
+    nextPageToken: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ChallengeSchemaType = z.infer<typeof ChallengeSchema>;
 export type ChallengeConfigSchemaType = z.infer<typeof ChallengeConfigSchema>;
@@ -200,5 +239,8 @@ export type AgentSchemaType = z.infer<typeof AgentSchema>;
 export type AgentsResponseType = z.infer<typeof AgentsResponseSchema>;
 export type RecordingMetadata = z.infer<typeof RecordingMetadataSchema>;
 export type RecordingsListResponse = z.infer<typeof RecordingsListResponseSchema>;
-export type RecordingDownloadUrlResponse = z.infer<typeof RecordingDownloadUrlResponseSchema>;
 export type RunParticipant = z.infer<typeof RunParticipantSchema>;
+export type DownloadUrlResponse = z.infer<typeof DownloadUrlResponseSchema>;
+export type WorldSchemaType = z.infer<typeof WorldSchema>;
+export type WorldConfigSchemaType = z.infer<typeof WorldConfigSchema>;
+export type WorldsResponseType = z.infer<typeof WorldsResponseSchema>;

package/dist/lib/schemas.js

@@ -64,6 +64,10 @@ export const UploadUrlResponseSchema = z.object({
     uploadUrl: z.string(),
     expiresAt: z.string(),
 });
+export const DownloadUrlResponseSchema = z.object({
+    downloadUrl: z.string(),
+    expiresAt: z.string(),
+});
 export const AgentSchema = z.object({
     username: z.string().optional(),
     name: z.string().optional(),
@@ -86,7 +90,24 @@ export const RecordingMetadataSchema = z.object({
 export const RecordingsListResponseSchema = z.object({
     recordings: z.array(RecordingMetadataSchema),
 });
-export const RecordingDownloadUrlResponseSchema = z.object({
-    downloadUrl: z.string(),
-    expiresAt: z.string(),
+export const WorldSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    description: z.string().nullish(),
+    visibility: z.enum(["private", "public"]),
+    creationTime: z.string(),
+    updateTime: z.string(),
+    creator: z.string(),
+});
+export const WorldConfigSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    visibility: z.enum(["private", "public"]),
+    domain: z.literal("minecraft").default("minecraft"),
+    metadata: z.record(z.string(), z.string()).optional(),
+});
+export const WorldsResponseSchema = z.object({
+    worlds: z.array(WorldSchema),
+    nextPageToken: z.string().optional(),
 });

package/dist/lib/utils.d.ts

@@ -86,6 +86,7 @@ export declare function executeCommand(command: string, args: string[], options?
  * @returns A promise that resolves with the stdout of the command.
  */
 export declare function executeNodeCommand(args: string[], env: Record<string, string>): Promise<string>;
+export declare function loadTypescriptExport(filePath: string, exportName: string, env?: Record<string, string>): Promise<unknown>;
 /**
  * Open a URL in the default browser.
  * This is fire-and-forget, so we don't wait for it to complete.

package/dist/lib/utils.js

@@ -168,6 +168,15 @@ export async function executeCommand(command, args, options) {
 export async function executeNodeCommand(args, env) {
     return executeCommand(process.execPath, args, { env });
 }
+export async function loadTypescriptExport(filePath, exportName, env = {}) {
+    const stdout = await executeNodeCommand([
+        "--experimental-transform-types",
+        "--no-warnings",
+        "-e",
+        `console.log(JSON.stringify(require("${filePath}").${exportName}));`,
+    ], env);
+    return JSON.parse(stdout);
+}
 /**
  * Open a URL in the default browser.
  * This is fire-and-forget, so we don't wait for it to complete.

package/dist/lib/world.d.ts

@@ -0,0 +1,21 @@
+import { type WorldConfigSchemaType } from "./schemas.js";
+/**
+ * Represents a Minecraft world stored locally as:
+ *   worlds/<slug>/config.ts    - metadata (name, visibility, etc.)
+ *   worlds/<slug>/world.tar.gz - the packaged world files
+ */
+export declare class World {
+    readonly shortSlug: string;
+    constructor(shortSlug: string);
+    get worldDir(): string;
+    get configPath(): string;
+    get tarballPath(): string;
+    exists(): boolean;
+    tarballExists(): boolean;
+    validateTarball(): Promise<boolean>;
+    loadConfig(): Promise<WorldConfigSchemaType>;
+    static getLocalWorlds(): Promise<string[]>;
+    static createLocal(slug: string, config: WorldConfigSchemaType): Promise<void>;
+    static createTarballFrom(sourcePath: string, slug: string): Promise<void>;
+    static toSlug(folderName: string): string;
+}

package/dist/lib/world.js

@@ -0,0 +1,102 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import * as tar from "tar";
+import { WorldConfigSchema } from "./schemas.js";
+import { loadTypescriptExport, readDirSorted } from "./utils.js";
+/**
+ * Represents a Minecraft world stored locally as:
+ *   worlds/<slug>/config.ts    - metadata (name, visibility, etc.)
+ *   worlds/<slug>/world.tar.gz - the packaged world files
+ */
+export class World {
+    shortSlug;
+    constructor(shortSlug) {
+        this.shortSlug = shortSlug;
+    }
+    get worldDir() {
+        return path.resolve(process.cwd(), "worlds", this.shortSlug);
+    }
+    get configPath() {
+        return path.join(this.worldDir, "config.ts");
+    }
+    get tarballPath() {
+        return path.join(this.worldDir, "world.tar.gz");
+    }
+    exists() {
+        return existsSync(this.worldDir) && existsSync(this.configPath);
+    }
+    tarballExists() {
+        return existsSync(this.tarballPath);
+    }
+    // Validates that the tarball contains level.dat (required for valid Minecraft worlds)
+    async validateTarball() {
+        if (!this.tarballExists()) {
+            return false;
+        }
+        const entries = [];
+        await tar.list({
+            file: this.tarballPath,
+            onReadEntry: (entry) => {
+                entries.push(entry.path);
+            },
+        });
+        return entries.some((entry) => entry === "level.dat" || entry.endsWith("/level.dat"));
+    }
+    async loadConfig() {
+        if (!existsSync(this.configPath)) {
+            throw new Error(`Config file not found at ${this.configPath}`);
+        }
+        const config = await loadTypescriptExport(this.configPath, "config");
+        return WorldConfigSchema.parse(config);
+    }
+    static async getLocalWorlds() {
+        const worldsDir = path.resolve(process.cwd(), "worlds");
+        if (!existsSync(worldsDir)) {
+            return [];
+        }
+        const entries = await readDirSorted(worldsDir);
+        const worlds = [];
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.parentPath === worldsDir) {
+                const configPath = path.join(worldsDir, entry.name, "config.ts");
+                if (existsSync(configPath)) {
+                    worlds.push(entry.name);
+                }
+            }
+        }
+        return worlds;
+    }
+    static async createLocal(slug, config) {
+        const world = new World(slug);
+        await fs.mkdir(world.worldDir, { recursive: true });
+        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);
+    }
+    static async createTarballFrom(sourcePath, slug) {
+        const resolvedSource = path.resolve(sourcePath);
+        if (!existsSync(resolvedSource)) {
+            throw new Error(`Source path does not exist: ${resolvedSource}`);
+        }
+        const levelDatPath = path.join(resolvedSource, "level.dat");
+        if (!existsSync(levelDatPath)) {
+            throw new Error(`Invalid Minecraft world: level.dat not found in ${resolvedSource}`);
+        }
+        const world = new World(slug);
+        await fs.mkdir(world.worldDir, { recursive: true });
+        await tar.create({
+            file: world.tarballPath,
+            gzip: true,
+            cwd: resolvedSource,
+        }, ["."]);
+    }
+    // Converts folder name to valid slug: "My World 2" -> "my-world-2"
+    static toSlug(folderName) {
+        return folderName
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .replace(/-+/g, "-");
+    }
+}