@kradle/cli 0.2.2 → 0.2.4

package/README.md

@@ -128,6 +128,7 @@ Run a challenge in production or studio environment:
 ```bash
 kradle challenge run <challenge-name>
 kradle challenge run <challenge-name> --studio  # Run in local studio environment
+kradle challenge run <team-name>:<challenge-name>  # Run a public challenge from another team
 ```
 
 ## Experiment Commands

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

@@ -11,7 +11,6 @@ export default class Run extends Command {
         "web-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         "studio-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>;
         studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         open: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/challenge/run.js

@@ -2,7 +2,6 @@ import { Command, Flags } from "@oclif/core";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
-import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 import { loadTemplateRun, openInBrowser } from "../../lib/utils.js";
 export default class Run extends Command {
@@ -10,27 +9,31 @@ export default class Run extends Command {
     static examples = [
         "<%= config.bin %> <%= command.id %> my-challenge",
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
+        "<%= config.bin %> <%= command.id %> team-name:my-challenge",
     ];
     static args = {
-        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to run" }),
+        challengeSlug: getChallengeSlugArgument({
+            description: "Challenge slug to run (e.g., 'my-challenge' or 'team-name:my-challenge')",
+            allowTeam: true,
+        }),
     };
     static flags = {
         studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
         open: Flags.boolean({ char: "o", description: "Open the run URL in the browser", default: false }),
-        ...getConfigFlags("api-key", "api-url", "challenges-path", "web-url", "studio-url", "studio-api-url"),
+        ...getConfigFlags("api-key", "api-url", "web-url", "studio-url", "studio-api-url"),
     };
     async run() {
         const { args, flags } = await this.parse(Run);
         const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
         const studioApi = new ApiClient(apiUrl, flags["api-key"], flags.studio);
-        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
+        const challengeSlug = args.challengeSlug;
         try {
             const { participants } = (await loadTemplateRun());
             const template = {
-                challenge: challenge.shortSlug,
+                challenge: challengeSlug,
                 participants,
             };
-            this.log(pc.blue(`>> Running challenge: ${challenge.shortSlug}${flags.studio ? " (studio)" : ""}...`));
+            this.log(pc.blue(`>> Running challenge: ${challengeSlug}${flags.studio ? " (studio)" : ""}...`));
             const response = await studioApi.runChallenge(template);
             if (response.runIds && response.runIds.length > 0) {
                 const baseUrl = flags.studio ? flags["studio-url"] : flags["web-url"];

package/dist/lib/arguments.d.ts

@@ -1,8 +1,12 @@
 import type { Arg } from "@oclif/core/interfaces";
 /**
- * Returns a "challenge slug" argument, and validates it to be a valid challenge slug.
+ * 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 getChallengeSlugArgument<R extends boolean = true>({ description, required, }: {
+export declare function getChallengeSlugArgument<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,15 +1,27 @@
 import { Args } from "@oclif/core";
-const CHALLENGE_SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// 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, and validates it to be a valid challenge slug.
+ * 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 getChallengeSlugArgument({ description, required, }) {
+export function getChallengeSlugArgument({ description, required, allowTeam = false, }) {
+    const regex = allowTeam ? NAMESPACED_SLUG_REGEX : LOCAL_SLUG_REGEX;
+    const errorMessage = allowTeam
+        ? "Challenge 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-challenge')."
+        : "Challenge 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 (!CHALLENGE_SLUG_REGEX.test(input)) {
-                throw new Error(`Invalid challenge slug: ${input}. Challenge slugs must be lowercase alphanumeric characters and hyphens, and must not start or end with a hyphen.`);
+            if (!regex.test(input)) {
+                throw new Error(`Invalid challenge slug: ${input}. ${errorMessage}`);
             }
             return input;
         },

package/oclif.manifest.json

@@ -86,54 +86,6 @@
         "list.js"
       ]
     },
-    "ai-docs:api": {
-      "aliases": [],
-      "args": {},
-      "description": "Output the Kradle API reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:api",
-      "pluginAlias": "@kradle/cli",
-      "pluginName": "@kradle/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "api.js"
-      ]
-    },
-    "ai-docs:cli": {
-      "aliases": [],
-      "args": {},
-      "description": "Output the Kradle CLI reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:cli",
-      "pluginAlias": "@kradle/cli",
-      "pluginName": "@kradle/cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "cli.js"
-      ]
-    },
     "challenge:build": {
       "aliases": [],
       "args": {
@@ -409,7 +361,7 @@
       "aliases": [],
       "args": {
         "challengeSlug": {
-          "description": "Challenge slug to run",
+          "description": "Challenge slug to run (e.g., 'my-challenge' or 'team-name:my-challenge')",
           "name": "challengeSlug",
           "required": true
         }
@@ -417,7 +369,8 @@
       "description": "Run a challenge",
       "examples": [
         "<%= config.bin %> <%= command.id %> my-challenge",
-        "<%= config.bin %> <%= command.id %> my-challenge --studio"
+        "<%= config.bin %> <%= command.id %> my-challenge --studio",
+        "<%= config.bin %> <%= command.id %> team-name:my-challenge"
       ],
       "flags": {
         "studio": {
@@ -453,15 +406,6 @@
           "multiple": false,
           "type": "option"
         },
-        "challenges-path": {
-          "description": "Absolute path to the challenges directory",
-          "env": "KRADLE_CHALLENGES_PATH",
-          "name": "challenges-path",
-          "default": "~/Documents/kradle-studio/challenges",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
         "web-url": {
           "description": "Kradle Web URL, used to display the run URL",
           "env": "KRADLE_WEB_URL",
@@ -574,6 +518,54 @@
         "watch.js"
       ]
     },
+    "ai-docs:api": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the Kradle API reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:api",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "api.js"
+      ]
+    },
+    "ai-docs:cli": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the Kradle CLI reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:cli",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "cli.js"
+      ]
+    },
     "experiment:create": {
       "aliases": [],
       "args": {
@@ -808,5 +800,5 @@
       ]
     }
   },
-  "version": "0.2.2"
+  "version": "0.2.4"
 }

package/package.json

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

package/static/ai_docs/LLM_API_REFERENCE.md

@@ -261,7 +261,7 @@ current_y_position: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
-    execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+    value.set(Actions.getCurrentPlayerPosition().y)
   },
 }
 ```
@@ -323,6 +323,8 @@ score.lowerOrEqualThan(number | Score);
 
 ### Lifecycle Events
 
+All lifecycle events run globally (not per-player).
+
 #### `start_challenge`
 
 Runs once when the challenge starts. Use for global setup.
@@ -337,19 +339,19 @@ start_challenge: () => {
 
 #### `init_participants`
 
-Runs once per player after start (delayed 1 second). Use for player setup.
+Runs 1 second after start_challenge. Use for player setup. It still runs globally.
 
 ```typescript
 init_participants: () => {
-  Actions.give({ target: "self", item: "minecraft:diamond_sword", count: 1 });
-  Actions.setAttribute({ target: "self", attribute_: "generic.max_health", value: 40 });
-  Actions.teleport({ target: "self", x: 0, y: 100, z: 0, absolute: true });
+  Actions.give({ target: "all", item: "minecraft:diamond_sword", count: 1 });
+  Actions.setAttribute({ target: "all", attribute_: "generic.max_health", value: 40 });
+  Actions.teleport({ target: "all", x: 0, y: 100, z: 0, absolute: true });
 }
 ```
 
 #### `on_tick`
 
-Runs every tick for each player. Use sparingly for performance.
+Runs every tick. Use sparingly for performance.
 
 ```typescript
 on_tick: () => {
@@ -402,7 +404,7 @@ Score events watch a variable and trigger when it reaches a specified target val
 ```typescript
 {
   score: variables.death_count,
-  mode: "fire_once",  // Triggers once when death_count changes from 0
+  mode: "fire_once",  // Triggers once when death_count changes away from initial value
   actions: () => {
     Actions.announce({ message: "First death!" });
   },
@@ -417,6 +419,8 @@ Score events watch a variable and trigger when it reaches a specified target val
 
 Advancement events trigger when a Minecraft advancement criterion is met. Internally, an advancement is created that grants when the criterion triggers, which then fires the event. The `criteria` array follows the [Minecraft Advancement JSON format](https://minecraft.fandom.com/wiki/Advancement/JSON_format).
 
+Advancement-based events always fire per-player.
+
 **Parameters:**
 - `criteria` (required): Array of advancement trigger objects with optional conditions
 - `mode` (required): `"fire_once"` or `"repeatable"`
@@ -476,6 +480,13 @@ See the [Minecraft Wiki](https://minecraft.fandom.com/wiki/Advancement/JSON_form
 
 ## Actions
 
+Actions are higher-level functions that wrap common Minecraft operations. They provide:
+- Automatic target mapping (`"all"`, `"self"`, team names → proper selectors)
+- Integration with Kradle's interface (e.g., `Actions.announce` messages appear in Kradle)
+- Consistent API for common operations
+
+For advanced use cases not covered by Actions, you can fall back to Sandstone's lower-level functions directly (`give`, `tellraw`, `effect`, `kill`, `execute`, etc.). See [Sandstone Integration](#sandstone-integration).
+
 All actions are called via the `Actions` object:
 
 ```typescript
@@ -497,28 +508,44 @@ Broadcast message to all players with KRADLE tag.
 
 ```typescript
 Actions.announce({
-  message: string;  // Message text
+  message: JSONTextComponent;  // Message (string or formatted object)
+});
+
+// Simple string:
+Actions.announce({ message: "Game starting!" });
+
+// Formatted JSONTextComponent:
+Actions.announce({
+  message: [
+    { text: "Player ", color: "white" },
+    { selector: "@s", color: "gold", bold: true },
+    { text: " won the game!", color: "green" }
+  ]
 });
 ```
 
 #### `Actions.tellraw(params)`
 
-Send formatted message to specific target.
+Send formatted message to specific target. **Note:** These messages are only visible to players in-game and will not appear in Kradle's interface. Use `Actions.announce` for messages that should be visible in Kradle.
 
 ```typescript
 Actions.tellraw({
-  target: TargetNames;  // "all", "self", or any selector
-  message: string[];    // Message array
+  target: TargetNames;       // "all", "self", or any selector
+  message: JSONTextComponent; // Message (string or formatted object)
 });
 
-// Example:
+// Examples:
 Actions.tellraw({
   target: "all",
   message: ["Hello, ", { text: "world!", color: "gold", bold: true }]
 });
 Actions.tellraw({
   target: "self",
-  message: ["You won!"]
+  message: "You won!"
+});
+Actions.tellraw({
+  target: "self",
+  message: { text: "Critical hit!", color: "red", bold: true }
 });
 ```
 
@@ -611,6 +638,39 @@ variables.my_diamond_count.set(count);
 
 **Note:** This action creates a temporary variable internally using `Variable()` and uses `execute.store.result.score` with `clear` command (count 0) to count items without removing them from the inventory.
 
+#### `Actions.getCurrentPlayerPosition()`
+
+Get the current player's position as x, y, z Score variables. Must be called in a player context (e.g., inside `forEveryPlayer`, individual variables updaters, or when `@s` is a player). This is the prefered way of checking a player's position.
+
+```typescript
+Actions.getCurrentPlayerPosition(): { x: Score; y: Score; z: Score }
+
+// Example - Check if player is above Y=100:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(pos.y.greaterThan(100), () => {
+  Actions.announce({ message: "You reached the sky!" });
+});
+
+// Example - Store position in custom variables:
+const { x, y, z } = Actions.getCurrentPlayerPosition();
+variables.player_x.set(x);
+variables.player_y.set(y);
+variables.player_z.set(z);
+
+// Example - Check if player is in a specific area:
+const pos = Actions.getCurrentPlayerPosition();
+_.if(_.and(
+  pos.x.greaterThan(0),
+  pos.x.lowerThan(100),
+  pos.z.greaterThan(0),
+  pos.z.lowerThan(100)
+), () => {
+  Actions.announce({ message: "You're in the zone!" });
+});
+```
+
+**Note:** This returns integer coordinates (block position). The values are truncated from the player's exact floating-point position.
+
 ### Entities
 
 #### `Actions.summonMultiple(params)`
@@ -1045,7 +1105,7 @@ createChallenge({
       Actions.announce({ message: "First to kill 2 pigs wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ pigs_farmed }) => [
@@ -1080,7 +1140,7 @@ createChallenge({
       type: "individual",
       objective_type: "dummy",
       updater: (value) => {
-        execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
+        value.set(Actions.getCurrentPlayerPosition().y)
       },
     },
     max_height: {
@@ -1124,8 +1184,8 @@ createChallenge({
       Actions.announce({ message: "Climb as high as you can!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:cobblestone", count: 64 });
-      Actions.give({ target: "self", item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
+      Actions.give({ target: "all", item: "minecraft:cobblestone", count: 64 });
     },
   }))
   .custom_events(() => [])
@@ -1176,9 +1236,9 @@ createChallenge({
       Actions.announce({ message: "Last player standing wins!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:stone_sword", count: 1 });
-      Actions.give({ target: "self", item: "minecraft:leather_chestplate", count: 1 });
-      Actions.give({ target: "self", item: "minecraft:cooked_beef", count: 10 });
+      Actions.give({ target: "all", item: "minecraft:stone_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:leather_chestplate", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:cooked_beef", count: 10 });
     },
   }))
   .custom_events(({ kills }) => [
@@ -1237,7 +1297,7 @@ createChallenge({
     },
     init_participants: () => {
       // Different items based on role would be set via role-specific logic
-      Actions.give({ target: "self", item: "minecraft:wooden_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:wooden_sword", count: 1 });
     },
   }))
   .custom_events(() => [])
@@ -1301,7 +1361,7 @@ createChallenge({
       Actions.announce({ message: "Capture the enemy flag and return to base!" });
     },
     init_participants: () => {
-      Actions.give({ target: "self", item: "minecraft:iron_sword", count: 1 });
+      Actions.give({ target: "all", item: "minecraft:iron_sword", count: 1 });
     },
   }))
   .custom_events(({ captured_flag }) => [
@@ -1378,6 +1438,10 @@ current_y: {
   type: "individual",
   objective_type: "dummy",
   updater: (value) => {
+    // Prefered way: using the dedicated Action
+    value.set(Actions.getCurrentPlayerPosition().y)
+
+    // Alternative way: using execute.store + data.get
     execute.as("@s").store.result.score(value).run.data.get.entity("@s", "Pos[1]");
   },
 }

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -260,17 +260,19 @@ Runs a challenge with configured participants.
 ```bash
 kradle challenge run <challenge-name>
 kradle challenge run <challenge-name> --studio
+kradle challenge run <team-name>:<challenge-name>
 ```
 
 **Arguments:**
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `challenge-name` | Challenge to run | Yes |
+| `challenge-name` | Challenge to run. Can be a short slug (e.g., `my-challenge`) or include a team/user namespace (e.g., `team-name:my-challenge`). The namespace is useful for running public challenges owned by other teams. If no namespace is provided, it defaults to the user's own namespace. | Yes |
 
 **Flags:**
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--studio` | Run in local studio environment instead of production | false |
+| `--open` | Open the run URL in the browser | false |
 
 **Prerequisites:**
 - `template-run.json` must exist in project root with participant configuration
@@ -294,9 +296,12 @@ kradle challenge run <challenge-name> --studio
 
 **Examples:**
 ```bash
-# Run in production
+# Run your own challenge in production
 kradle challenge run my-challenge
 
+# Run a public challenge from another team
+kradle challenge run team-kradle:battle-royale
+
 # Run in local studio
 kradle challenge run my-challenge --studio
 ```