@kradle/cli 0.2.4 → 0.2.5

package/README.md

@@ -111,6 +111,19 @@ List all challenges (local and cloud):
 kradle challenge list
 ```
 
+### Pull Challenge
+
+Download a challenge from the cloud and extract source files locally:
+
+```bash
+kradle challenge pull                                  # Interactive selection
+kradle challenge pull <challenge-name>                 # Pull your own challenge
+kradle challenge pull <team-name>:<challenge-name>     # Pull a public challenge from another team
+kradle challenge pull <challenge-name> --yes           # Skip confirmation when overwriting
+```
+
+This downloads the challenge tarball, extracts `challenge.ts` and `config.ts`, and builds the datapack locally.
+
 ### Watch Challenge
 
 Watch a challenge for changes and auto-rebuild/upload:

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

@@ -0,0 +1,15 @@
+import { Command } from "@oclif/core";
+export default class Pull extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        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>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/challenge/pull.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import * as tar from "tar";
+import { ApiClient } from "../../lib/api-client.js";
+import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
+import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
+import { getConfigFlags } from "../../lib/flags.js";
+export default class Pull extends Command {
+    static description = "Pull a challenge from the cloud and extract source files locally";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> username:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes",
+    ];
+    static args = {
+        challengeSlug: getChallengeSlugArgument({
+            description: "Challenge slug to pull (interactive selection if omitted)",
+            required: false,
+            allowTeam: true,
+        }),
+    };
+    static flags = {
+        yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Pull);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        let challengeSlug = args.challengeSlug;
+        if (!challengeSlug) {
+            const [kradleChallenges, cloudChallenges, localChallenges] = await Promise.all([
+                api.listKradleChallenges(),
+                api.listChallenges(),
+                Challenge.getLocalChallenges(),
+            ]);
+            const allChallenges = [...kradleChallenges, ...cloudChallenges];
+            if (allChallenges.length === 0) {
+                this.error(pc.red("No challenges found in the cloud."));
+            }
+            const localSet = new Set(localChallenges);
+            const slugs = allChallenges.map((c) => c.slug).sort();
+            const choices = slugs.map((slug) => {
+                const shortSlug = extractShortSlug(slug);
+                const isLocal = localSet.has(shortSlug);
+                const status = isLocal ? pc.yellow(" (local)") : "";
+                return {
+                    name: slug,
+                    message: `${slug}${status}`,
+                };
+            });
+            const response = await enquirer.prompt({
+                type: "select",
+                name: "challenge",
+                message: "Select a challenge to pull",
+                choices,
+            });
+            challengeSlug = response.challenge;
+        }
+        const shortSlug = extractShortSlug(challengeSlug);
+        const challenge = new Challenge(shortSlug, flags["challenges-path"]);
+        const existsInCloud = await api.challengeExists(challengeSlug);
+        if (!existsInCloud) {
+            this.error(pc.red(`Challenge "${challengeSlug}" does not exist in the cloud.`));
+        }
+        const existsLocally = existsSync(challenge.challengeDir);
+        const hasLocalFiles = existsLocally && (existsSync(challenge.challengePath) || existsSync(challenge.configPath));
+        if (hasLocalFiles && !flags.yes) {
+            this.log(pc.bold(`\nChallenge: ${pc.cyan(challenge.shortSlug)}`));
+            this.log(`  Local folder exists: ${pc.yellow(challenge.challengeDir)}`);
+            if (existsSync(challenge.challengePath)) {
+                this.log(`  challenge.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            if (existsSync(challenge.configPath)) {
+                this.log(`  config.ts: ${pc.yellow("exists (will be overwritten)")}`);
+            }
+            this.log("");
+            try {
+                const response = await enquirer.prompt({
+                    type: "confirm",
+                    name: "confirm",
+                    message: `Overwrite local challenge files? ${pc.red("This cannot be undone.")}`,
+                    initial: false,
+                });
+                if (!response.confirm) {
+                    this.log(pc.yellow("Pull cancelled"));
+                    return;
+                }
+            }
+            catch {
+                this.log(pc.yellow("\nPull cancelled"));
+                return;
+            }
+        }
+        const tempTarballPath = path.join(flags["challenges-path"], `${challenge.shortSlug}-pull-temp.tar.gz`);
+        const tasks = new Listr([
+            {
+                title: "Downloading challenge tarball",
+                task: async (_, task) => {
+                    const { downloadUrl } = await api.getChallengeDownloadUrl(challengeSlug);
+                    const response = await fetch(downloadUrl);
+                    if (!response.ok) {
+                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+                    }
+                    const buffer = await response.arrayBuffer();
+                    await fs.mkdir(path.dirname(tempTarballPath), { recursive: true });
+                    await fs.writeFile(tempTarballPath, Buffer.from(buffer));
+                    task.title = "Downloaded challenge tarball";
+                },
+            },
+            {
+                title: "Creating challenge directory",
+                task: async (_, task) => {
+                    await fs.mkdir(challenge.challengeDir, { recursive: true });
+                    task.title = `Created directory: ${challenge.challengeDir}`;
+                },
+            },
+            {
+                title: "Extracting source files",
+                task: async (_, task) => {
+                    const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
+                    const tempExtractDir = path.join(flags["challenges-path"], `${challenge.shortSlug}-extract-temp`);
+                    await fs.mkdir(tempExtractDir, { recursive: true });
+                    try {
+                        await tar.extract({
+                            file: tempTarballPath,
+                            cwd: tempExtractDir,
+                            filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
+                        });
+                        const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
+                        const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
+                        let extractedCount = 0;
+                        if (existsSync(srcChallengeTs)) {
+                            await fs.copyFile(srcChallengeTs, challenge.challengePath);
+                            extractedCount++;
+                        }
+                        if (existsSync(srcConfigTs)) {
+                            await fs.copyFile(srcConfigTs, challenge.configPath);
+                            extractedCount++;
+                        }
+                        if (extractedCount === 0) {
+                            throw new Error(`No source files found in tarball. The challenge may not have been built with source files.`);
+                        }
+                        task.title = `Extracted ${extractedCount} source file(s)`;
+                    }
+                    finally {
+                        await fs.rm(tempExtractDir, { recursive: true, force: true });
+                    }
+                },
+            },
+            {
+                title: "Cleaning up",
+                task: async (_, task) => {
+                    await fs.rm(tempTarballPath, { force: true });
+                    task.title = "Cleaned up temporary files";
+                },
+            },
+            {
+                title: "Building datapack",
+                task: async (_, task) => {
+                    await challenge.build(true);
+                    task.title = "Built datapack";
+                },
+            },
+        ]);
+        try {
+            await tasks.run();
+            this.log(pc.green(`\n✓ Challenge pulled: ${challenge.shortSlug}`));
+            this.log(pc.dim(`  → challenge.ts: ${challenge.challengePath}`));
+            this.log(pc.dim(`  → config.ts: ${challenge.configPath}`));
+        }
+        catch (error) {
+            await fs.rm(tempTarballPath, { force: true }).catch(() => { });
+            this.error(pc.red(`Pull failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}

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

@@ -66,6 +66,12 @@ export declare class ApiClient {
      * @returns The upload URL.
      */
     getChallengeUploadUrl(slug: string): Promise<string>;
+    /**
+     * Get the download URL for a challenge datapack.
+     * @param slug - The slug of the challenge.
+     * @returns The download URL and expiration time.
+     */
+    getChallengeDownloadUrl(slug: string): Promise<RecordingDownloadUrlResponse>;
     runChallenge(runData: {
         challenge: string;
         participants: unknown[];

package/dist/lib/api-client.js

@@ -210,6 +210,14 @@ export class ApiClient {
         const response = await this.get(`challenges/${slug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
         return response.uploadUrl;
     }
+    /**
+     * Get the download URL for a challenge datapack.
+     * @param slug - The slug of the challenge.
+     * @returns The download URL and expiration time.
+     */
+    async getChallengeDownloadUrl(slug) {
+        return this.get(`challenges/${slug}/datapackDownloadUrl`, {}, RecordingDownloadUrlResponseSchema);
+    }
     async runChallenge(runData) {
         const url = "jobs";
         const payload = this.isStudio ? runData : { ...runData, jobType: "background" };

package/dist/lib/arguments.d.ts

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

package/dist/lib/arguments.js

@@ -1,16 +1,13 @@
 import { Args } from "@oclif/core";
-// Base pattern for a slug segment (lowercase alphanumeric with hyphens, no leading/trailing hyphens)
 const SLUG_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
-// Local challenge slug pattern: just the challenge name (no namespace)
 const LOCAL_SLUG_REGEX = new RegExp(`^${SLUG_SEGMENT}$`);
-// Full challenge slug pattern: optional namespace prefix (e.g., "team-name:") followed by the challenge slug
 const NAMESPACED_SLUG_REGEX = new RegExp(`^(?:${SLUG_SEGMENT}:)?${SLUG_SEGMENT}$`);
-/**
- * Returns a "challenge slug" argument, validating it to be a valid challenge slug.
- * @param description - Description for the argument
- * @param required - Whether the argument is required (default: true)
- * @param allowTeam - Whether to allow namespaced slugs like "team-name:my-challenge" (default: false)
- */
+export function extractShortSlug(slug) {
+    if (slug.includes(":")) {
+        return slug.split(":")[1];
+    }
+    return slug;
+}
 export function getChallengeSlugArgument({ description, required, allowTeam = false, }) {
     const regex = allowTeam ? NAMESPACED_SLUG_REGEX : LOCAL_SLUG_REGEX;
     const errorMessage = allowTeam

package/oclif.manifest.json

@@ -86,6 +86,54 @@
         "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": {
@@ -357,6 +405,75 @@
         "list.js"
       ]
     },
+    "challenge:pull": {
+      "aliases": [],
+      "args": {
+        "challengeSlug": {
+          "description": "Challenge slug to pull (interactive selection if omitted)",
+          "name": "challengeSlug",
+          "required": false
+        }
+      },
+      "description": "Pull a challenge from the cloud and extract source files locally",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> username:my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge --yes"
+      ],
+      "flags": {
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "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"
+        },
+        "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"
+        },
+        "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"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "challenge:pull",
+      "pluginAlias": "@kradle/cli",
+      "pluginName": "@kradle/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "challenge",
+        "pull.js"
+      ]
+    },
     "challenge:run": {
       "aliases": [],
       "args": {
@@ -518,54 +635,6 @@
         "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": {
@@ -800,5 +869,5 @@
       ]
     }
   },
-  "version": "0.2.4"
+  "version": "0.2.5"
 }

package/package.json

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

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -223,6 +223,61 @@ kradle challenge list
 
 ---
 
+### `kradle challenge pull [name]`
+
+Downloads a challenge from the cloud and extracts source files locally.
+
+**Usage:**
+```bash
+kradle challenge pull
+kradle challenge pull <challenge-name>
+kradle challenge pull <team-name>:<challenge-name>
+kradle challenge pull <challenge-name> --yes
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `challenge-name` | Challenge slug to pull. Can be a short slug (e.g., `my-challenge`) or include a team/user namespace (e.g., `team-name:my-challenge`). If omitted, shows interactive selection. | No |
+
+**Flags:**
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--yes` | `-y` | Skip confirmation prompts when overwriting local files | false |
+
+**What it does:**
+1. Downloads the challenge tarball from cloud storage
+2. Extracts `challenge.ts` and `config.ts` from the `.src` folder in the tarball
+3. Places files in `challenges/<short-slug>/` directory
+4. Builds the datapack locally
+
+**Interactive mode (no slug argument):**
+- Shows list of all cloud challenges (your own + team-kradle)
+- Marks challenges that exist locally with "(local)" indicator
+- Select a challenge to pull
+
+**Confirmation prompt:**
+When pulling over existing local files (without `--yes`), shows:
+- Which files will be overwritten
+- Asks for confirmation before proceeding
+
+**Examples:**
+```bash
+# Interactive selection from all cloud challenges
+kradle challenge pull
+
+# Pull your own challenge
+kradle challenge pull my-challenge
+
+# Pull a public challenge from another team
+kradle challenge pull team-kradle:example-challenge
+
+# Pull without confirmation prompt
+kradle challenge pull my-challenge --yes
+```
+
+---
+
 ### `kradle challenge watch <name>`
 
 Watches a challenge for file changes and automatically rebuilds/uploads.
@@ -663,6 +718,7 @@ kradle challenge build --all --visibility public
 | `kradle challenge build --all` | Build all challenges |
 | `kradle challenge delete <name>` | Delete challenge |
 | `kradle challenge list` | List all challenges |
+| `kradle challenge pull [name]` | Pull challenge from cloud |
 | `kradle challenge watch <name>` | Watch and auto-rebuild |
 | `kradle challenge run <name>` | Run challenge |
 | `kradle experiment create <name>` | Create new experiment |