kradle 0.6.6 → 0.6.7

package/README.md

@@ -81,23 +81,24 @@ This creates a `challenges/<challenge-name>/` folder with:
 
 ### Build Challenge
 
-Build, validate, and upload challenge datapack:
+Build and validate challenge datapacks locally, with optional upload:
 
 ```bash
 kradle challenge build <challenge-name>
+kradle challenge build <challenge-name> --no-upload    # Build locally only (no cloud upload)
 kradle challenge build <challenge-name> --no-validate  # Skip validation
 kradle challenge build <challenge-name> --public       # Upload as public
 kradle challenge build --all                           # Build all local challenges
 ```
 
 This command:
-1. Creates the challenge in the cloud (if it doesn't already exist)
-2. Builds the datapack by executing `challenge.ts`
-3. Validates the datapack using Spyglass (blocks upload if errors found)
-4. Uploads `config.ts` to cloud
-5. Uploads the datapack to GCS
+1. Builds the datapack by executing `challenge.ts`
+2. Validates the datapack using Spyglass (unless `--no-validate`)
+3. If upload is enabled (default), creates the challenge in the cloud if needed
+4. If upload is enabled (default), uploads `config.ts` and datapack
 
-Validation checks `.mcfunction` files for syntax errors, invalid commands, and other issues. Use `--no-validate` to skip this step.
+Use `--no-upload` to build locally only. Use `--no-validate` to skip validation.
+`--public` is only valid when upload is enabled (default).
 
 ### Delete Challenge
 
@@ -478,7 +479,7 @@ Each challenge is a folder in `challenges/<slug>/` containing:
 1. `kradle challenge create <slug>` creates the folder with `challenge.ts`
 2. The create command automatically builds, uploads, and downloads the config from the cloud API
 3. The downloaded JSON is converted into a typed TypeScript `config.ts` file
-4. `kradle challenge build <slug>` automatically uploads `config.ts` (if it exists) before building the datapack
+4. `kradle challenge build <slug>` builds datapacks locally and uploads `config.ts` + datapack by default (use `--no-upload` for local-only build)
 5. You can modify `config.ts` locally and run `build` to sync changes to the cloud
 
 ## Architecture

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

@@ -6,13 +6,15 @@ export default class Build extends Command {
         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>;
         all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         public: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "no-validate": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-upload": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     static strict: boolean;
     run(): Promise<void>;
+    private requireApiKey;
 }

package/dist/commands/challenge/build.js

@@ -5,7 +5,7 @@ import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.
 import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Build extends Command {
-    static description = "Build and upload challenge datapack and config";
+    static description = "Build challenge datapack locally, with optional upload";
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge my-other-challenge",
@@ -13,7 +13,7 @@ export default class Build extends Command {
     ];
     static args = {
         challengeSlug: getChallengeSlugArgument({
-            description: "Challenge slug to build and upload. Can be used multiple times to build and upload multiple challenges at once. Incompatible with --all flag.",
+            description: "Challenge slug to build. Can be used multiple times to build multiple challenges at once. Incompatible with --all flag.",
             required: false,
         }),
     };
@@ -21,10 +21,23 @@ export default class Build extends Command {
         all: Flags.boolean({ char: "a", description: "Build all challenges in the challenges directory", default: false }),
         public: Flags.boolean({ char: "p", description: "Upload challenges as public.", default: false }),
         "no-validate": Flags.boolean({
-            description: "Skip datapack validation before upload",
+            description: "Skip datapack validation",
             default: false,
         }),
-        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+        "no-upload": Flags.boolean({
+            description: "Build datapack locally only (skip cloud config/datapack upload)",
+            default: false,
+        }),
+        "api-url": Flags.string({
+            description: "Kradle Web API URL",
+            env: "KRADLE_API_URL",
+            default: "https://api.kradle.ai/v0",
+        }),
+        "api-key": Flags.string({
+            description: "Kradle API key",
+            env: "KRADLE_API_KEY",
+        }),
+        ...getConfigFlags("challenges-path"),
     };
     static strict = false;
     async run() {
@@ -32,6 +45,9 @@ export default class Build extends Command {
         if (flags.all && argv.length > 0) {
             this.error(pc.red("Cannot use --all flag with challenge slugs"));
         }
+        if (flags["no-upload"] && flags.public) {
+            this.error(pc.red("Cannot use --public with --no-upload"));
+        }
         if (!flags.all && argv.length === 0) {
             // Show help if no challenge slugs are provided - https://github.com/oclif/oclif/issues/183#issuecomment-1933104981
             await new (await loadHelpClass(this.config))(this.config).showHelp([Build.id]);
@@ -41,7 +57,8 @@ export default class Build extends Command {
             this.log(pc.blue("Building all challenges"));
         }
         const challengeSlugs = flags.all ? await Challenge.getLocalChallenges() : argv;
-        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const shouldUpload = !flags["no-upload"];
+        const api = shouldUpload ? new ApiClient(flags["api-url"], this.requireApiKey(flags["api-key"])) : null;
         for (const challengeSlug of challengeSlugs) {
             // Validate that the challenge exists locally
             const validation = await Challenge.validateForLocalOperation(challengeSlug, flags["challenges-path"]);
@@ -51,10 +68,17 @@ export default class Build extends Command {
             const challenge = new Challenge(extractShortSlug(challengeSlug), flags["challenges-path"]);
             this.log(pc.blue(`==== Building challenge: ${challenge.shortSlug} ====`));
             try {
-                await challenge.buildAndUpload(api, {
-                    asPublic: flags.public,
-                    validate: !flags["no-validate"],
-                });
+                if (shouldUpload && api) {
+                    await challenge.buildAndUpload(api, {
+                        asPublic: flags.public,
+                        validate: !flags["no-validate"],
+                    });
+                }
+                else {
+                    await challenge.buildLocal({
+                        validate: !flags["no-validate"],
+                    });
+                }
             }
             catch (error) {
                 this.error(pc.red(`Build failed: ${error instanceof Error ? error.message : String(error)}`));
@@ -62,4 +86,11 @@ export default class Build extends Command {
             this.log();
         }
     }
+    requireApiKey(apiKey) {
+        if (apiKey) {
+            return apiKey;
+        }
+        this.error(pc.red("Missing required flag --api-key (or KRADLE_API_KEY) unless using --no-upload"));
+        throw new Error("Unreachable");
+    }
 }

package/dist/lib/challenge.d.ts

@@ -51,6 +51,18 @@ export declare class Challenge {
      */
     build(silent?: boolean, config?: ChallengeConfigSchemaType): Promise<void>;
     loadConfig(): Promise<ChallengeConfigSchemaType>;
+    /**
+     * Build the challenge datapack locally.
+     * @param options - Build options
+     * @param options.validate - Whether to validate the datapack after build (default: true).
+     * @returns The loaded config and datapack hash.
+     */
+    buildLocal(options?: {
+        validate?: boolean;
+    }): Promise<{
+        config: ChallengeConfigSchemaType;
+        datapackHash: string;
+    }>;
     /**
      * Build the challenge datapack and upload it to the cloud.
      * @param api - The API client to use.

package/dist/lib/challenge.js

@@ -162,17 +162,15 @@ export class Challenge {
         }
     }
     /**
-     * Build the challenge datapack and upload it to the cloud.
-     * @param api - The API client to use.
+     * Build the challenge datapack locally.
      * @param options - Build options
-     * @param options.asPublic - Whether the challenge should be uploaded as public.
-     * @param options.validate - Whether to validate the datapack before upload (default: true).
-     * @returns The config and datapack hash.
+     * @param options.validate - Whether to validate the datapack after build (default: true).
+     * @returns The loaded config and datapack hash.
      */
-    async buildAndUpload(api, options = { asPublic: false, validate: true }) {
-        const { asPublic, validate = true } = options;
+    async buildLocal(options = { validate: true }) {
+        const { validate = true } = options;
         // Start validation service initialization in parallel with build (if validation enabled)
-        // This overlaps the ~1.5s init time with the build process
+        // This overlaps the init time with the build process.
         let validationService = null;
         if (validate) {
             validationService = ValidationService.create(this.builtDatapackPath);
@@ -182,19 +180,12 @@ export class Challenge {
             await validationService?.close();
             throw new Error(`Challenge "${this.shortSlug}" does not exist locally. Make sure both the challenge.ts file and the config.ts file exist.`);
         }
-        // Ensure challenge exists in the cloud
-        if (!(await api.challengeExists(this.shortSlug))) {
-            console.log(pc.yellow(`Challenge not found in cloud: ${this.shortSlug}`));
-            console.log(pc.yellow(`Creating challenge: ${this.shortSlug}`));
-            await api.createChallenge(this.shortSlug);
-            console.log(pc.green(`✓ Challenge created in cloud`));
-        }
         const config = await this.loadConfig();
         // Build datapack (validation service initializes in parallel)
         console.log(pc.blue(`>> Building datapack: ${this.shortSlug}`));
         await this.build(false, config);
         console.log(pc.green(`✓  Datapack built\n`));
-        // Validate datapack before uploading (if enabled)
+        // Validate datapack after building (if enabled)
         if (validate && validationService) {
             console.log(pc.blue(`>> Validating datapack: ${this.shortSlug}`));
             try {
@@ -202,13 +193,34 @@ export class Challenge {
                 console.log(formatValidationResult(validationResult));
                 console.log();
                 if (validationResult.hasErrors) {
-                    throw new Error(`Validation failed with ${validationResult.errors.length} error(s). Upload aborted.`);
+                    throw new Error(`Validation failed with ${validationResult.errors.length} error(s). Build aborted.`);
                 }
             }
             finally {
                 await validationService.close();
             }
         }
+        const datapackHash = await this.getDatapackHash();
+        return { config, datapackHash };
+    }
+    /**
+     * Build the challenge datapack and upload it to the cloud.
+     * @param api - The API client to use.
+     * @param options - Build options
+     * @param options.asPublic - Whether the challenge should be uploaded as public.
+     * @param options.validate - Whether to validate the datapack before upload (default: true).
+     * @returns The config and datapack hash.
+     */
+    async buildAndUpload(api, options = { asPublic: false, validate: true }) {
+        const { asPublic, validate = true } = options;
+        const { config, datapackHash } = await this.buildLocal({ validate });
+        // Ensure challenge exists in the cloud
+        if (!(await api.challengeExists(this.shortSlug))) {
+            console.log(pc.yellow(`Challenge not found in cloud: ${this.shortSlug}`));
+            console.log(pc.yellow(`Creating challenge: ${this.shortSlug}`));
+            await api.createChallenge(this.shortSlug);
+            console.log(pc.green(`✓ Challenge created in cloud`));
+        }
         // Ensure challenge's visibility is set to private - else, temporarily set it to private
         const cloudChallengeVisibility = (await api.getChallenge(this.shortSlug, ["visibility"])).visibility;
         if (cloudChallengeVisibility === "public") {
@@ -230,7 +242,6 @@ export class Challenge {
             await api.updateChallengeVisibility(this.shortSlug, "public");
             console.log(pc.green(`✓  Challenge visibility set to public\n`));
         }
-        const datapackHash = await this.getDatapackHash();
         return { config, datapackHash };
     }
     /**

package/dist/lib/validator.js

@@ -12,6 +12,8 @@ import pc from "picocolors";
  */
 const FILTERED_ERROR_MESSAGES = [
     "Fake names cannot be longer than 40 characters", // Actually they can be longer
+    "Objective names cannot be longer than 16 characters", // Actually they can be longer
+    "Player names cannot be longer than 16 characters", // Actually they can be longer
 ];
 /**
  * Get a human-readable severity label with color

package/oclif.manifest.json

@@ -215,12 +215,12 @@
       "aliases": [],
       "args": {
         "challengeSlug": {
-          "description": "Challenge slug to build and upload. Can be used multiple times to build and upload multiple challenges at once. Incompatible with --all flag.",
+          "description": "Challenge slug to build. Can be used multiple times to build multiple challenges at once. Incompatible with --all flag.",
           "name": "challengeSlug",
           "required": false
         }
       },
-      "description": "Build and upload challenge datapack and config",
+      "description": "Build challenge datapack locally, with optional upload",
       "examples": [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge my-other-challenge",
@@ -242,30 +242,34 @@
           "type": "boolean"
         },
         "no-validate": {
-          "description": "Skip datapack validation before upload",
+          "description": "Skip datapack validation",
           "name": "no-validate",
           "allowNo": false,
           "type": "boolean"
         },
-        "api-key": {
-          "description": "Kradle API key",
-          "env": "KRADLE_API_KEY",
-          "name": "api-key",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "no-upload": {
+          "description": "Build datapack locally only (skip cloud config/datapack upload)",
+          "name": "no-upload",
+          "allowNo": false,
+          "type": "boolean"
         },
         "api-url": {
           "description": "Kradle Web API URL",
           "env": "KRADLE_API_URL",
           "name": "api-url",
-          "required": true,
           "default": "https://api.kradle.ai/v0",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "challenges-path": {
           "description": "Absolute path to the challenges directory",
           "env": "KRADLE_CHALLENGES_PATH",
@@ -1524,5 +1528,5 @@
       ]
     }
   },
-  "version": "0.6.6"
+  "version": "0.6.7"
 }

package/package.json

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

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -119,11 +119,12 @@ kradle challenge create my-first-challenge
 
 ### `kradle challenge build <name>`
 
-Builds a challenge datapack, validates it, and uploads everything to the cloud.
+Builds a challenge datapack locally, validates it, and optionally uploads to the cloud.
 
 **Usage:**
 ```bash
 kradle challenge build <challenge-name>
+kradle challenge build <challenge-name> --no-upload
 kradle challenge build <challenge-name> --public
 kradle challenge build <challenge-name> --no-validate
 kradle challenge build --all
@@ -140,21 +141,24 @@ kradle challenge build --all --public
 |------|-------|-------------|---------|
 | `--all` | `-a` | Build all local challenges | false |
 | `--public` | `-p` | Set visibility to public after upload | false |
-| `--no-validate` | | Skip datapack validation before upload | false |
+| `--no-validate` | | Skip datapack validation | false |
+| `--no-upload` | | Build locally only (skip cloud config/datapack upload) | false |
+
+`--public` is incompatible with `--no-upload`.
 
 **What it does:**
-1. Creates the challenge in cloud if it doesn't exist
-2. Executes `challenge.ts` to generate the datapack
+1. Executes `challenge.ts` to generate the datapack
    - Passes `KRADLE_CHALLENGE_END_STATES` env var containing a JSON array of end state keys from `config.endStates` (e.g., `["victory", "defeat"]`)
    - Passes `KRADLE_CHALLENGE_ROLES` env var containing a JSON array of role names from `config.roles` (e.g., `["attacker", "defender"]`)
    - Passes `KRADLE_CHALLENGE_LOCATIONS` env var containing a JSON array of location keys from `config.challengeConfig.locations` (e.g., `["spawn", "goal"]`)
    - The `@kradle/challenges-sdk` uses these to register valid end states, roles, and locations at build time
-3. Validates the datapack using Spyglass engine (unless `--no-validate`)
+2. Validates the datapack using Spyglass engine (unless `--no-validate`)
    - Checks `.mcfunction` files for syntax errors, invalid commands, JSON text components
-   - **Errors block the upload** - fix them before the challenge can be uploaded
+   - **Errors block command completion** - fix them before the build can finish
    - Auto-detects Minecraft version from `pack.mcmeta` `pack_format`
-4. Uploads `config.ts` metadata to cloud
-5. Compresses and uploads datapack to cloud storage
+3. If upload is enabled (default), creates challenge in cloud if needed
+4. If upload is enabled (default), uploads `config.ts` metadata to cloud
+5. If upload is enabled (default), compresses and uploads datapack to cloud storage
 
 **Validation Output:**
 ```
@@ -164,7 +168,7 @@ data/kradle/functions/init.mcfunction:5:1 warning: Unused objective
 
 Found 1 error, 1 warning
 
-Error: Validation failed with 1 error(s). Upload aborted.
+Error: Validation failed with 1 error(s). Build aborted.
 ```
 
 **Examples:**
@@ -172,6 +176,9 @@ Error: Validation failed with 1 error(s). Upload aborted.
 # Build single challenge (with validation)
 kradle challenge build my-challenge
 
+# Build local datapack only (no cloud upload)
+kradle challenge build my-challenge --no-upload
+
 # Build and make public
 kradle challenge build my-challenge --public
 
@@ -1274,7 +1281,7 @@ kradle challenge build --all --public
 |---------|-------------|
 | `kradle init` | Initialize new project |
 | `kradle challenge create <name>` | Create new challenge |
-| `kradle challenge build <name>` | Build and upload challenge |
+| `kradle challenge build <name>` | Build challenge (uploads by default) |
 | `kradle challenge build --all` | Build all challenges |
 | `kradle challenge delete <name>` | Delete challenge |
 | `kradle challenge list` | List all challenges |