kradle 0.6.5 → 0.6.7

package/README.md

@@ -81,17 +81,24 @@ This creates a `challenges/<challenge-name>/` folder with:
 
 ### Build Challenge
 
-Build challenge datapack and upload both config and 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 exists)
-2. Uploads `config.ts` to cloud (if it exists)
-3. Builds the datapack by executing `challenge.ts`
-4. 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
+
+Use `--no-upload` to build locally only. Use `--no-validate` to skip validation.
+`--public` is only valid when upload is enabled (default).
 
 ### Delete Challenge
 
@@ -132,9 +139,11 @@ Watch a challenge for changes and auto-rebuild/upload:
 
 ```bash
 kradle challenge watch <challenge-name>
+kradle challenge watch <challenge-name> --no-validate  # Skip validation
+kradle challenge watch <challenge-name> --verbose      # Verbose output
 ```
 
-Uses file watching with debouncing (300ms) and hash comparison to minimize unnecessary rebuilds.
+Uses file watching with debouncing (1 second) and hash comparison to minimize unnecessary rebuilds. Validation runs after each build but doesn't block uploads in watch mode (errors are displayed but the upload continues).
 
 ### Run Challenge
 
@@ -470,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,12 +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,14 +13,31 @@ 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,
         }),
     };
     static flags = {
         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 }),
-        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+        "no-validate": Flags.boolean({
+            description: "Skip datapack validation",
+            default: false,
+        }),
+        "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() {
@@ -28,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]);
@@ -37,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"]);
@@ -47,7 +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, flags.public);
+                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)}`));
@@ -55,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/commands/challenge/watch.d.ts

@@ -7,6 +7,7 @@ export default class Watch extends Command {
         "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>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "no-validate": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static args: {
         challengeSlug: import("@oclif/core/interfaces").Arg<string>;

package/dist/commands/challenge/watch.js

@@ -8,11 +8,16 @@ import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.
 import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 import { clearScreen, debounced } from "../../lib/utils.js";
+import { formatValidationResult, ValidationService } from "../../lib/validator.js";
 export default class Watch extends Command {
     static description = "Watch a challenge for changes and auto-rebuild/upload";
     static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
     static flags = {
         verbose: Flags.boolean({ description: "Enable verbose output", default: false }),
+        "no-validate": Flags.boolean({
+            description: "Skip datapack validation",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url", "challenges-path"),
     };
     static args = {
@@ -31,8 +36,28 @@ export default class Watch extends Command {
         let building = false;
         // Perform the initial build and upload
         this.log(pc.blue(`Performing initial build and upload...`));
-        let { config: lastConfig, datapackHash: lastHash } = await challenge.buildAndUpload(api, false);
+        let { config: lastConfig, datapackHash: lastHash } = await challenge.buildAndUpload(api, {
+            asPublic: false,
+            validate: !flags["no-validate"],
+        });
         this.log(pc.green(`✓ Initial build and upload complete`));
+        // Create a reusable validation service for watch mode (42ms per validation vs 1.8s)
+        // The service is initialized once and reused for all subsequent validations
+        let validationService = null;
+        if (!flags["no-validate"]) {
+            validationService = ValidationService.create(challenge.builtDatapackPath);
+            // Wait for initial initialization
+            await validationService.waitUntilReady();
+        }
+        // Clean up validation service on exit
+        const cleanup = async () => {
+            if (validationService) {
+                await validationService.close();
+            }
+            process.exit(0);
+        };
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
         const executeRebuild = async () => {
             building = true;
             // Clear screen before subsequent rebuilds for clean output
@@ -66,8 +91,29 @@ export default class Watch extends Command {
                         task.title = "Datapack built";
                     },
                 },
+                {
+                    title: "Validating datapack",
+                    skip: () => (flags["no-validate"] || !validationService ? "Validation skipped" : false),
+                    task: async (ctx, task) => {
+                        // Use the reusable validation service (42ms vs 1.8s for new service each time)
+                        const validationResult = await validationService.validate();
+                        ctx.validationFailed = validationResult.hasErrors;
+                        ctx.validationOutput = formatValidationResult(validationResult);
+                        if (validationResult.hasErrors) {
+                            throw new Error(`${validationResult.errors.length} error${validationResult.errors.length !== 1 ? "s" : ""}`);
+                        }
+                        else if (validationResult.warnings.length > 0) {
+                            task.title = `Validation complete (${validationResult.warnings.length} warning${validationResult.warnings.length !== 1 ? "s" : ""})`;
+                        }
+                        else {
+                            task.title = "Validation passed";
+                        }
+                    },
+                    exitOnError: false,
+                },
                 {
                     title: "Checking datapack changes",
+                    skip: (ctx) => (ctx.validationFailed ? "Upload skipped due to validation errors" : false),
                     task: async (_ctx, task) => {
                         const newHash = await challenge.getDatapackHash();
                         // Upload if datapack changed OR if config changed (since tarball includes source files)
@@ -87,8 +133,14 @@ export default class Watch extends Command {
                 renderer: flags.verbose ? "verbose" : "default",
             });
             try {
-                await tasks.run();
-                this.log(pc.green(`\n✓ Rebuild complete`));
+                const ctx = await tasks.run();
+                if (ctx.validationFailed) {
+                    this.log(`\n${ctx.validationOutput}`);
+                    this.log(pc.red(`\n✗ Upload skipped due to validation errors`));
+                }
+                else {
+                    this.log(pc.green(`\n✓ Rebuild complete`));
+                }
             }
             catch (error) {
                 this.log(pc.red(`\n✗ Error: ${error instanceof Error ? error.message : String(error)}`));

package/dist/lib/challenge.d.ts

@@ -1,5 +1,6 @@
 import type { ApiClient } from "./api-client.js";
 import { type ChallengeConfigSchemaType, type ChallengeSchemaType } from "./schemas.js";
+import { type ValidationResult } from "./validator.js";
 export declare const SOURCE_FOLDER = ".src";
 export declare class Challenge {
     readonly shortSlug: string;
@@ -25,6 +26,16 @@ export declare class Challenge {
      * Get the path to the tarball file
      */
     get tarballPath(): string;
+    /**
+     * Get the path to the built datapack directory (inside datapackPath)
+     */
+    get builtDatapackPath(): string;
+    /**
+     * Validate the built datapack using Spyglass
+     * @returns ValidationResult with categorized issues
+     * @throws Error if datapack doesn't exist
+     */
+    validate(): Promise<ValidationResult>;
     /**
      * Make sure the challenge exists locally and is valid by ensuring the challenge.ts file and the config.ts file exist.
      */
@@ -40,13 +51,30 @@ 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.
-     * @param asPublic - Whether the challenge should be uploaded as public.
+     * @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.
      */
-    buildAndUpload(api: ApiClient, asPublic: boolean): Promise<{
+    buildAndUpload(api: ApiClient, options?: {
+        asPublic: boolean;
+        validate?: boolean;
+    }): Promise<{
         config: ChallengeConfigSchemaType;
         datapackHash: string;
     }>;

package/dist/lib/challenge.js

@@ -7,6 +7,7 @@ import * as tar from "tar";
 import { extractShortSlug, isNamespacedSlug } from "./arguments.js";
 import { ChallengeConfigSchema } from "./schemas.js";
 import { executeTypescriptFile, findSimilarStrings, getStaticResourcePath, loadTypescriptExport, readDirSorted, } from "./utils.js";
+import { formatValidationResult, ValidationService, validateDatapack } from "./validator.js";
 import { formatError } from "./zod-errors.js";
 export const SOURCE_FOLDER = ".src";
 export class Challenge {
@@ -46,6 +47,23 @@ export class Challenge {
     get tarballPath() {
         return path.join(this.kradleChallengesPath, `${this.shortSlug}.tar.gz`);
     }
+    /**
+     * Get the path to the built datapack directory (inside datapackPath)
+     */
+    get builtDatapackPath() {
+        return path.join(this.datapackPath, "datapack");
+    }
+    /**
+     * Validate the built datapack using Spyglass
+     * @returns ValidationResult with categorized issues
+     * @throws Error if datapack doesn't exist
+     */
+    async validate() {
+        if (!existsSync(this.builtDatapackPath)) {
+            throw new Error(`Datapack not found at ${this.builtDatapackPath}. Run build first.`);
+        }
+        return validateDatapack(this.builtDatapackPath);
+    }
     /**
      * Make sure the challenge exists locally and is valid by ensuring the challenge.ts file and the config.ts file exist.
      */
@@ -144,16 +162,58 @@ export class Challenge {
         }
     }
     /**
-     * Build the challenge datapack and upload it to the cloud.
-     * @param api - The API client to use.
-     * @param asPublic - Whether the challenge should be uploaded as public.
-     * @returns The config and datapack hash.
+     * 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.
      */
-    async buildAndUpload(api, asPublic) {
+    async buildLocal(options = { validate: true }) {
+        const { validate = true } = options;
+        // Start validation service initialization in parallel with build (if validation enabled)
+        // This overlaps the init time with the build process.
+        let validationService = null;
+        if (validate) {
+            validationService = ValidationService.create(this.builtDatapackPath);
+        }
         // Ensure challenge exists locally
         if (!this.exists()) {
+            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.`);
         }
+        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 after building (if enabled)
+        if (validate && validationService) {
+            console.log(pc.blue(`>> Validating datapack: ${this.shortSlug}`));
+            try {
+                const validationResult = await validationService.validate();
+                console.log(formatValidationResult(validationResult));
+                console.log();
+                if (validationResult.hasErrors) {
+                    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}`));
@@ -161,7 +221,6 @@ export class Challenge {
             await api.createChallenge(this.shortSlug);
             console.log(pc.green(`✓ Challenge created in cloud`));
         }
-        const config = await this.loadConfig();
         // 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") {
@@ -174,18 +233,15 @@ export class Challenge {
         // We have to set it to private because we cannot update public challenges
         await api.updateChallenge(this.shortSlug, config, "private");
         console.log(pc.green(`✓  Config uploaded\n`));
-        // Build and upload datapack
-        console.log(pc.blue(`>> Building datapack: ${this.shortSlug}`));
-        await this.build(false, config);
+        // Upload datapack
         console.log(pc.blue(`>> Uploading datapack: ${this.shortSlug}`));
         await api.uploadChallengeDatapack(this.shortSlug, this.tarballPath);
-        console.log(pc.green(`✓  Build & upload complete for ${this.shortSlug}\n`));
+        console.log(pc.green(`✓  Datapack uploaded\n`));
         if (asPublic) {
             console.log(pc.green(`👀 Setting challenge visibility to public...`));
             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.d.ts

@@ -0,0 +1,62 @@
+import { ErrorSeverity } from "@spyglassmc/core";
+export interface ValidationError {
+    uri: string;
+    filePath: string;
+    line: number;
+    character: number;
+    endLine: number;
+    endCharacter: number;
+    message: string;
+    severity: ErrorSeverity;
+}
+export interface ValidationResult {
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    infos: ValidationError[];
+    hints: ValidationError[];
+    hasErrors: boolean;
+    totalIssues: number;
+}
+/**
+ * Format validation errors for CLI output
+ */
+export declare function formatValidationResult(result: ValidationResult): string;
+/**
+ * Reusable validation service that keeps Spyglass initialized.
+ * Use this for watch mode or when validating multiple times.
+ */
+export declare class ValidationService {
+    private service;
+    private rootUri;
+    private errorMap;
+    private readyPromise;
+    private constructor();
+    private initialize;
+    /**
+     * Create a new validation service for a datapack.
+     * Returns immediately - call waitUntilReady() or validate() to wait for initialization.
+     */
+    static create(datapackPath: string): ValidationService;
+    /**
+     * Wait until the service is fully initialized.
+     */
+    waitUntilReady(): Promise<void>;
+    /**
+     * Validate all mcfunction files in the datapack.
+     * Waits for initialization if not already complete.
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Notify the service that a file has changed (for watch mode).
+     */
+    notifyFileChanged(filePath: string): Promise<void>;
+    /**
+     * Close the service and clean up resources.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Validate a Minecraft datapack using Spyglass (simple one-shot API).
+ * For repeated validations, use ValidationService instead.
+ */
+export declare function validateDatapack(datapackPath: string): Promise<ValidationResult>;

package/dist/lib/validator.js

@@ -0,0 +1,285 @@
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ConfigService, ErrorSeverity, Logger, Service, VanillaConfig } from "@spyglassmc/core";
+import { getNodeJsExternals } from "@spyglassmc/core/lib/nodejs.js";
+import { initialize as initializeJavaEdition } from "@spyglassmc/java-edition";
+import { initialize as initializeMcdoc } from "@spyglassmc/mcdoc";
+import pc from "picocolors";
+/**
+ * List of error messages to filter out (Spyglass false positives)
+ */
+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
+ */
+function getSeverityLabel(severity) {
+    switch (severity) {
+        case ErrorSeverity.Error:
+            return pc.red("error");
+        case ErrorSeverity.Warning:
+            return pc.yellow("warning");
+        case ErrorSeverity.Information:
+            return pc.blue("info");
+        case ErrorSeverity.Hint:
+            return pc.dim("hint");
+        default:
+            return pc.dim("unknown");
+    }
+}
+/**
+ * Read a specific line from a file
+ */
+function getSourceLine(uri, lineNumber) {
+    try {
+        const filePath = uri.startsWith("file://") ? fileURLToPath(uri) : uri;
+        const content = readFileSync(filePath, "utf-8");
+        const lines = content.split("\n");
+        if (lineNumber >= 0 && lineNumber < lines.length) {
+            return lines[lineNumber];
+        }
+    }
+    catch {
+        // Ignore file read errors
+    }
+    return null;
+}
+/**
+ * Format validation errors for CLI output
+ */
+export function formatValidationResult(result) {
+    if (result.totalIssues === 0) {
+        return pc.green("No validation issues found");
+    }
+    const lines = [];
+    const allIssues = [...result.errors, ...result.warnings, ...result.infos, ...result.hints];
+    // Group by file
+    const byFile = new Map();
+    for (const issue of allIssues) {
+        const existing = byFile.get(issue.filePath) || [];
+        existing.push(issue);
+        byFile.set(issue.filePath, existing);
+    }
+    // Sort files and output
+    const sortedFiles = [...byFile.keys()].sort();
+    for (const filePath of sortedFiles) {
+        const fileIssues = byFile.get(filePath);
+        if (!fileIssues)
+            continue;
+        // Sort by line, then character
+        fileIssues.sort((a, b) => a.line - b.line || a.character - b.character);
+        for (const issue of fileIssues) {
+            // Line numbers are 0-indexed from Spyglass, display as 1-indexed
+            const location = pc.cyan(`${filePath}:${issue.line + 1}:${issue.character + 1}`);
+            const severity = getSeverityLabel(issue.severity);
+            lines.push(`${location} ${severity}: ${issue.message}`);
+            // Show source line with caret marker
+            const sourceLine = getSourceLine(issue.uri, issue.line);
+            if (sourceLine !== null) {
+                lines.push(pc.dim(`  ${sourceLine}`));
+                // Add caret marker pointing to the error column
+                const caretPadding = " ".repeat(issue.character + 2); // +2 for the "  " prefix
+                lines.push(pc.red(`${caretPadding}^`));
+            }
+        }
+    }
+    // Summary
+    const summary = [];
+    if (result.errors.length > 0) {
+        summary.push(pc.red(`${result.errors.length} error${result.errors.length !== 1 ? "s" : ""}`));
+    }
+    if (result.warnings.length > 0) {
+        summary.push(pc.yellow(`${result.warnings.length} warning${result.warnings.length !== 1 ? "s" : ""}`));
+    }
+    if (result.infos.length > 0) {
+        summary.push(pc.blue(`${result.infos.length} info`));
+    }
+    if (result.hints.length > 0) {
+        summary.push(pc.dim(`${result.hints.length} hint${result.hints.length !== 1 ? "s" : ""}`));
+    }
+    lines.push("");
+    lines.push(`Found ${summary.join(", ")}`);
+    return lines.join("\n");
+}
+/**
+ * Reusable validation service that keeps Spyglass initialized.
+ * Use this for watch mode or when validating multiple times.
+ */
+export class ValidationService {
+    service;
+    rootUri;
+    errorMap = new Map();
+    readyPromise;
+    constructor(service, rootUri) {
+        this.service = service;
+        this.rootUri = rootUri;
+        // Listen for document errors
+        this.service.project.on("documentErrored", (event) => {
+            const fileUri = event.uri;
+            // Skip archive files (vanilla data)
+            if (fileUri.startsWith("archive://")) {
+                return;
+            }
+            // Convert URI back to relative path
+            const filePath = fileUri.startsWith(this.rootUri)
+                ? fileUri.slice(this.rootUri.length)
+                : fileUri.replace("file://", "");
+            for (const error of event.errors) {
+                const key = `${fileUri}:${error.posRange.start.line}:${error.posRange.start.character}:${error.message}`;
+                if (!this.errorMap.has(key)) {
+                    this.errorMap.set(key, {
+                        uri: fileUri,
+                        filePath,
+                        line: error.posRange.start.line,
+                        character: error.posRange.start.character,
+                        endLine: error.posRange.end.line,
+                        endCharacter: error.posRange.end.character,
+                        message: error.message,
+                        severity: error.severity,
+                    });
+                }
+            }
+        });
+        // Start initialization immediately
+        this.readyPromise = this.initialize();
+    }
+    async initialize() {
+        await this.service.project.init();
+        await this.service.project.ready();
+    }
+    /**
+     * Create a new validation service for a datapack.
+     * Returns immediately - call waitUntilReady() or validate() to wait for initialization.
+     */
+    static create(datapackPath) {
+        // Convert to file URI format required by Spyglass (must end with /)
+        let rootUriStr = pathToFileURL(datapackPath).href;
+        if (!rootUriStr.endsWith("/")) {
+            rootUriStr += "/";
+        }
+        const rootUri = rootUriStr;
+        // Cache directory for Spyglass - use temp directory (no persistent cache for now)
+        const cacheDir = path.join(os.tmpdir(), "kradle-spyglass-cache");
+        const cacheRoot = `${pathToFileURL(cacheDir).href}/`;
+        const service = new Service({
+            isDebugging: false,
+            logger: Logger.noop(),
+            project: {
+                defaultConfig: ConfigService.merge(VanillaConfig, {
+                    env: {
+                        // Only load @vanilla-mcdoc - sufficient for mcfunction syntax validation
+                        // Skips @vanilla-datapack (6835 files) and @vanilla-resourcepack (8473 files)
+                        dependencies: ["@vanilla-mcdoc"],
+                        // Disable features we don't need for CLI validation
+                        feature: {
+                            codeActions: false,
+                            colors: false,
+                            completions: false,
+                            documentHighlighting: false,
+                            documentLinks: false,
+                            foldingRanges: false,
+                            formatting: false,
+                            hover: false,
+                            inlayHint: false,
+                            semanticColoring: false,
+                            selectionRanges: false,
+                            signatures: false,
+                        },
+                    },
+                }),
+                cacheRoot,
+                externals: getNodeJsExternals({ cacheRoot }),
+                // IMPORTANT: mcdoc.initialize must come BEFORE je.initialize
+                initializers: [initializeMcdoc, initializeJavaEdition],
+                projectRoots: [rootUri],
+            },
+        });
+        return new ValidationService(service, rootUri);
+    }
+    /**
+     * Wait until the service is fully initialized.
+     */
+    async waitUntilReady() {
+        await this.readyPromise;
+    }
+    /**
+     * Validate all mcfunction files in the datapack.
+     * Waits for initialization if not already complete.
+     */
+    async validate() {
+        await this.readyPromise;
+        // Clear previous errors
+        this.errorMap.clear();
+        // Get all tracked mcfunction files in the project (not from archives)
+        const trackedFiles = this.service.project
+            .getTrackedFiles()
+            .filter((uri) => uri.startsWith(this.rootUri) && uri.endsWith(".mcfunction"));
+        // For full JSON text component validation, we need to explicitly open and check each file
+        for (const fileUri of trackedFiles) {
+            try {
+                const contentBytes = await this.service.project.externals.fs.readFile(fileUri);
+                if (contentBytes !== undefined) {
+                    const content = new TextDecoder().decode(contentBytes);
+                    await this.service.project.onDidOpen(fileUri, "mcfunction", 1, content);
+                    await this.service.project.ensureClientManagedChecked(fileUri);
+                }
+            }
+            catch {
+                // Ignore file read errors
+            }
+        }
+        // Get all collected errors - only keep actual errors (not warnings) and filter out false positives
+        const errors = Array.from(this.errorMap.values()).filter((e) => e.severity === ErrorSeverity.Error && !FILTERED_ERROR_MESSAGES.includes(e.message));
+        return {
+            errors,
+            warnings: [],
+            infos: [],
+            hints: [],
+            hasErrors: errors.length > 0,
+            totalIssues: errors.length,
+        };
+    }
+    /**
+     * Notify the service that a file has changed (for watch mode).
+     */
+    async notifyFileChanged(filePath) {
+        await this.readyPromise;
+        const fileUri = pathToFileURL(filePath).href;
+        try {
+            const contentBytes = await this.service.project.externals.fs.readFile(fileUri);
+            if (contentBytes !== undefined) {
+                const content = new TextDecoder().decode(contentBytes);
+                // Increment version to signal change
+                await this.service.project.onDidChange(fileUri, [{ text: content }], 2);
+                await this.service.project.ensureClientManagedChecked(fileUri);
+            }
+        }
+        catch {
+            // Ignore file read errors
+        }
+    }
+    /**
+     * Close the service and clean up resources.
+     */
+    async close() {
+        await this.service.project.close();
+    }
+}
+/**
+ * Validate a Minecraft datapack using Spyglass (simple one-shot API).
+ * For repeated validations, use ValidationService instead.
+ */
+export async function validateDatapack(datapackPath) {
+    const service = ValidationService.create(datapackPath);
+    try {
+        return await service.validate();
+    }
+    finally {
+        await service.close();
+    }
+}

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",
@@ -241,25 +241,35 @@
           "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-validate": {
+          "description": "Skip datapack validation",
+          "name": "no-validate",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "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",
@@ -696,6 +706,12 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "no-validate": {
+          "description": "Skip datapack validation",
+          "name": "no-validate",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "api-key": {
           "description": "Kradle API key",
           "env": "KRADLE_API_KEY",
@@ -1512,5 +1528,5 @@
       ]
     }
   },
-  "version": "0.6.5"
+  "version": "0.6.7"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kradle",
-	"version": "0.6.5",
+	"version": "0.6.7",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"
@@ -37,6 +37,9 @@
 		"@oclif/core": "^4.8.0",
 		"@oclif/plugin-autocomplete": "^3.2.39",
 		"@oclif/plugin-help": "^6.2.35",
+		"@spyglassmc/core": "^0.4.43",
+		"@spyglassmc/java-edition": "^0.3.55",
+		"@spyglassmc/mcfunction": "^0.2.46",
 		"chokidar": "^4.0.3",
 		"dotenv": "^17.2.3",
 		"enquirer": "^2.4.1",

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -119,14 +119,16 @@ kradle challenge create my-first-challenge
 
 ### `kradle challenge build <name>`
 
-Builds a challenge datapack 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> --visibility public
+kradle challenge build <challenge-name> --no-upload
+kradle challenge build <challenge-name> --public
+kradle challenge build <challenge-name> --no-validate
 kradle challenge build --all
-kradle challenge build --all --visibility public
+kradle challenge build --all --public
 ```
 
 **Arguments:**
@@ -135,28 +137,53 @@ kradle challenge build --all --visibility public
 | `challenge-name` | Challenge to build | Yes (unless `--all`) |
 
 **Flags:**
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--all` | Build all local challenges | false |
-| `--visibility` | Set visibility (`private` or `public`) | private |
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--all` | `-a` | Build all local challenges | false |
+| `--public` | `-p` | Set visibility to public after 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. Uploads `config.ts` metadata to cloud
-3. 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
-4. Compresses and uploads datapack to cloud storage
+2. Validates the datapack using Spyglass engine (unless `--no-validate`)
+   - Checks `.mcfunction` files for syntax errors, invalid commands, JSON text components
+   - **Errors block command completion** - fix them before the build can finish
+   - Auto-detects Minecraft version from `pack.mcmeta` `pack_format`
+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:**
+```
+>> Validating datapack: my-challenge
+data/kradle/functions/tick.mcfunction:1:23 error: Unknown function 'kradle:undefined'
+data/kradle/functions/init.mcfunction:5:1 warning: Unused objective
+
+Found 1 error, 1 warning
+
+Error: Validation failed with 1 error(s). Build aborted.
+```
 
 **Examples:**
 ```bash
-# Build single challenge
+# 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 --visibility public
+kradle challenge build my-challenge --public
+
+# Build without validation (for quick iteration)
+kradle challenge build my-challenge --no-validate
 
 # Build all challenges
 kradle challenge build --all
@@ -289,6 +316,8 @@ Watches a challenge for file changes and automatically rebuilds/uploads.
 **Usage:**
 ```bash
 kradle challenge watch <challenge-name>
+kradle challenge watch <challenge-name> --no-validate
+kradle challenge watch <challenge-name> --verbose
 ```
 
 **Arguments:**
@@ -296,17 +325,29 @@ kradle challenge watch <challenge-name>
 |----------|-------------|----------|
 | `challenge-name` | Challenge to watch | Yes |
 
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--no-validate` | Skip datapack validation | false |
+| `--verbose` | Enable verbose output | false |
+
 **Behavior:**
 - Monitors `challenges/<name>/` directory for changes
-- Debounces rebuilds (300ms delay)
-- Only uploads if datapack hash changed
+- Debounces rebuilds (1 second delay)
+- Validates datapack after each build (unless `--no-validate`)
+  - In watch mode, validation errors are shown but **don't block upload** (allows iteration)
+  - Warnings and hints are displayed for awareness
+- Only uploads if datapack hash changed or config changed
 - Press Ctrl+C to stop watching
 
 **Example:**
 ```bash
 kradle challenge watch my-challenge
 # Now edit challenges/my-challenge/challenge.ts
-# Changes will automatically rebuild and upload
+# Changes will automatically rebuild, validate, and upload
+
+# Skip validation for faster iteration
+kradle challenge watch my-challenge --no-validate
 ```
 
 ---
@@ -1204,10 +1245,10 @@ kradle experiment recordings agent-benchmark --all
 
 ```bash
 # Build with public visibility
-kradle challenge build my-challenge --visibility public
+kradle challenge build my-challenge --public
 
 # Or build all challenges as public
-kradle challenge build --all --visibility public
+kradle challenge build --all --public
 ```
 
 ---
@@ -1240,7 +1281,7 @@ kradle challenge build --all --visibility 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 |