@kradle/cli 0.2.1 → 0.2.3

package/README.md

@@ -1,3 +1,5 @@
+<!-- This file is for human consumption. If you are an LLM or any AI Agent, make sure to read static/ai_docs/LLM_CLI_REFERENCE.md for an exhaustive explanation of this package. -->
+
 # Kradle CLI
 
 Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
@@ -8,6 +10,7 @@ Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
 * [Challenge](#challenge-commands)
 * [Experiments](#experiment-commands)
 * [Agents](#agent-commands)
+* [AI Docs](#ai-docs-commands)
 * [Publishing a New Version](#publishing-a-new-version)
 * [Development](#development)
 * [Architecture](#architecture)
@@ -125,18 +128,9 @@ 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
 ```
 
-### Multi-Upload
-
-Interactively select and upload multiple challenges:
-
-```bash
-kradle challenge multi-upload
-```
-
-Provides an interactive UI to select multiple challenges and uploads them in parallel.
-
 ## Experiment Commands
 
 Experiments allow you to run batches of challenge runs with different agents and configurations, then analyze the results. This is useful for benchmarking agents, testing challenge difficulty, or gathering statistics across many runs.
@@ -172,9 +166,10 @@ This creates `experiments/<name>/config.ts` with a template that you can customi
 Execute or resume an experiment:
 
 ```bash
-kradle experiment run <name>                  # Resume current version or create first one
-kradle experiment run <name> --new-version            # Start a new version
-kradle experiment run <name> --max-concurrent 10  # Control parallelism (default: 5)
+kradle experiment run <name>                       # Resume current version or create first one
+kradle experiment run <name> --new-version         # Start a new version
+kradle experiment run <name> --max-concurrent 10   # Control parallelism (default: 5)
+kradle experiment run <name> --download-recordings # Auto-download recordings as runs complete
 ```
 
 The run command:
@@ -184,6 +179,20 @@ The run command:
 4. Saves progress periodically (allows resuming if interrupted)
 5. Opens Metabase dashboard with results when complete
 
+### Download Recordings
+
+Download gameplay recordings from completed experiment runs:
+
+```bash
+kradle experiment recordings <name>                  # Interactive selection of run and participant
+kradle experiment recordings <name> <run-id>         # Download specific run
+kradle experiment recordings <name> --all            # Download all runs and participants
+kradle experiment recordings <name> --version 2      # Download from specific version
+kradle experiment recordings <name> <run-id> --all   # Download all participants for a run
+```
+
+Recordings are saved to `experiments/<name>/versions/<version>/recordings/<run-id>/`.
+
 ### List Experiments
 
 List all local experiments:
@@ -202,6 +211,26 @@ List all agents registered in the system:
 kradle agent list
 ```
 
+## AI Docs Commands
+
+Output LLM-focused documentation to stdout. These commands are designed to provide AI agents with comprehensive reference material about the Kradle CLI and API.
+
+### CLI Reference
+
+Output the CLI reference documentation:
+
+```bash
+kradle ai-docs cli
+```
+
+### API Reference
+
+Output the API reference documentation for the `@kradle/challenges` package:
+
+```bash
+kradle ai-docs api
+```
+
 ## Publishing a New Version
 
 The CLI uses GitHub Actions for automated releases. To publish a new version:
@@ -303,6 +332,7 @@ kradle-cli/
 ├── src/
 │   ├── commands/             # CLI commands
 │   │   ├── agent/            # Agent commands
+│   │   ├── ai-docs/          # AI documentation commands
 │   │   ├── challenge/        # Challenge management commands
 │   │   └── experiment/       # Experiment commands
 │   └── lib/                  # Core libraries

package/dist/commands/ai-docs/api.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class Api extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/ai-docs/api.js

@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+import { Command } from "@oclif/core";
+import { getStaticResourcePath } from "../../lib/utils.js";
+export default class Api extends Command {
+    static description = "Output the Kradle API reference documentation for LLMs";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        await this.parse(Api);
+        const docPath = getStaticResourcePath("ai_docs/LLM_API_REFERENCE.md");
+        const content = await fs.readFile(docPath, "utf-8");
+        this.log(content);
+    }
+}

package/dist/commands/ai-docs/cli.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class Cli extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/ai-docs/cli.js

@@ -0,0 +1,13 @@
+import fs from "node:fs/promises";
+import { Command } from "@oclif/core";
+import { getStaticResourcePath } from "../../lib/utils.js";
+export default class Cli extends Command {
+    static description = "Output the Kradle CLI reference documentation for LLMs";
+    static examples = ["<%= config.bin %> <%= command.id %>"];
+    async run() {
+        await this.parse(Cli);
+        const docPath = getStaticResourcePath("ai_docs/LLM_CLI_REFERENCE.md");
+        const content = await fs.readFile(docPath, "utf-8");
+        this.log(content);
+    }
+}

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/commands/init.js

@@ -104,13 +104,15 @@ export default class Init extends Command {
                         const templateDir = getStaticResourcePath("project_template");
                         const templateFiles = await readDirSorted(templateDir);
                         for (const file of templateFiles) {
-                            if (file.name.endsWith(".env")) {
-                                // We ignore .env as it will be created later
+                            // We ignore .env as it will be created later
+                            if (file.name.endsWith(".env") || file.isDirectory()) {
                                 continue;
                             }
                             const srcPath = path.join(file.parentPath, file.name);
                             const srcRelativePath = path.relative(templateDir, srcPath);
                             const destPath = path.join(targetDir, srcRelativePath);
+                            // Ensure the destination directory exists before copying the file
+                            await fs.mkdir(path.dirname(destPath), { recursive: true });
                             await fs.copyFile(srcPath, destPath);
                         }
                         // Create .env file based on the environment

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

@@ -361,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
         }
@@ -369,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": {
@@ -405,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",
@@ -526,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": {
@@ -760,5 +800,5 @@
       ]
     }
   },
-  "version": "0.2.1"
+  "version": "0.2.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kradle/cli",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"
@@ -81,6 +81,9 @@
 			},
 			"experiment": {
 				"description": "Manage and run experiments"
+			},
+			"ai-docs": {
+				"description": "Output LLM reference documentation"
 			}
 		}
 	}