@kradle/cli 0.0.17 → 0.2.0

package/dist/lib/api-client.js

@@ -1,4 +1,6 @@
-import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, HumanSchema, RunResponseSchema, RunStatusSchema, UploadUrlResponseSchema, } from "./schemas.js";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, HumanSchema, JobResponseSchema, RecordingDownloadUrlResponseSchema, RecordingsListResponseSchema, RunStatusSchema, UploadUrlResponseSchema, } from "./schemas.js";
 const DEFAULT_PAGE_SIZE = 30;
 const DEFAULT_CHALLENGE_SCHEMA = {
     slug: "",
@@ -21,37 +23,40 @@ const DEFAULT_CHALLENGE_SCHEMA = {
     },*/,
 };
 export class ApiClient {
-    config;
-    constructor(config) {
-        this.config = config;
+    apiUrl;
+    kradleApiKey;
+    isStudio;
+    constructor(apiUrl, kradleApiKey, isStudio = false) {
+        this.apiUrl = apiUrl;
+        this.kradleApiKey = kradleApiKey;
+        this.isStudio = isStudio;
     }
-    async request(target, url, options) {
-        const baseUrl = target === "web" ? this.config.WEB_API_URL : this.config.STUDIO_API_URL;
-        const fullUrl = `${baseUrl}/${url}`;
+    async request(endpoint, options) {
+        const fullUrl = `${this.apiUrl}/${endpoint}`;
         const response = await fetch(fullUrl, {
             ...options,
             headers: {
-                Authorization: `Bearer ${this.config.KRADLE_API_KEY}`,
+                Authorization: `Bearer ${this.kradleApiKey}`,
                 "Content-Type": "application/json",
                 ...options.headers,
             },
         });
         if (!response.ok) {
             const text = await response.text();
-            throw new Error(`API call failed: ${url} - ${response.status} ${response.statusText}\n${text}`);
+            throw new Error(`API call failed: ${fullUrl} - ${response.status} ${response.statusText}\n${text}`);
         }
         return response;
     }
-    async get(target, url, options = {}, schema) {
-        const response = await this.request(target, url, {
+    async get(url, options = {}, schema) {
+        const response = await this.request(url, {
             method: "GET",
             ...options,
         });
         const data = await response.json();
         return schema ? schema.parse(data) : data;
     }
-    async post(target, url, options = {}, schema) {
-        const response = await this.request(target, url, {
+    async post(url, options = {}, schema) {
+        const response = await this.request(url, {
             method: "POST",
             ...options,
         });
@@ -62,14 +67,14 @@ export class ApiClient {
         const data = JSON.parse(text);
         return schema ? schema.parse(data) : data;
     }
-    async put(target, url, options = {}) {
-        return await this.request(target, url, {
+    async put(url, options = {}) {
+        return await this.request(url, {
             method: "PUT",
             ...options,
         });
     }
-    async delete(target, url, options = {}) {
-        return await this.request(target, url, {
+    async delete(url, options = {}) {
+        return await this.request(url, {
             method: "DELETE",
             ...options,
         });
@@ -97,7 +102,7 @@ export class ApiClient {
             if (pageToken)
                 params.set("page_token", pageToken);
             params.set("page_size", String(pageSize));
-            const response = await this.get("web", `${url}?${params}`, {
+            const response = await this.get(`${url}?${params}`, {
                 headers: {
                     "Content-Type": "application/json",
                 },
@@ -109,7 +114,7 @@ export class ApiClient {
     }
     async getHuman() {
         const url = "human";
-        return this.get("web", url, {}, HumanSchema);
+        return this.get(url, {}, HumanSchema);
     }
     async listChallenges() {
         return this.listResource("challenges", "challenges", ChallengesResponseSchema);
@@ -122,7 +127,7 @@ export class ApiClient {
     }
     async getChallenge(challengeId) {
         const url = `challenges/${challengeId}`;
-        return this.get("web", url, {}, ChallengeSchema);
+        return this.get(url, {}, ChallengeSchema);
     }
     /**
      * Check if a challenge exists in the cloud.
@@ -132,7 +137,7 @@ export class ApiClient {
     async challengeExists(slug) {
         const url = `challenges/${slug}`;
         try {
-            const res = await this.get("web", url, {});
+            const res = await this.get(url, {});
             return res !== null && res !== undefined;
         }
         catch (error) {
@@ -142,37 +147,79 @@ export class ApiClient {
     async createChallenge(slug) {
         const challenge = { ...DEFAULT_CHALLENGE_SCHEMA, slug: slug, name: slug };
         const url = "challenges";
-        return this.post("web", url, {
+        return this.post(url, {
             body: JSON.stringify(challenge),
         });
     }
     /**
      * Update a challenge definition in the cloud.
-     * @param challenge - The challenge to update.
-     * @param challengeConfig - The challenge config to upload. If not provided, the config will be loaded from the challenge.
+     * @param challengeSlug - The slug of the challenge.
+     * @param challengeConfig - The challenge config to upload.
+     * @param visibility - The visibility to set.
      * @returns The updated challenge.
      */
-    async updateChallenge(challenge, challengeConfig) {
-        const url = `challenges/${challenge.shortSlug}`;
-        console.log(url);
-        const config = challengeConfig ?? (await challenge.loadConfig());
-        await this.put("web", url, {
-            body: JSON.stringify(config),
+    async updateChallenge(challengeSlug, challengeConfig, visibility) {
+        const url = `challenges/${challengeSlug}`;
+        const fullConfig = { ...challengeConfig, slug: challengeSlug, visibility };
+        await this.put(url, {
+            body: JSON.stringify(fullConfig),
         });
     }
-    async getChallengeUploadUrl(challenge) {
-        const response = await this.get("web", `challenges/${challenge.shortSlug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
+    /**
+     * Update the visibility of a challenge.
+     * @param challengeSlug - The slug of the challenge.
+     * @param visibility - The visibility to set.
+     * @returns The updated challenge.
+     */
+    async updateChallengeVisibility(challengeSlug, visibility) {
+        const url = `challenges/${challengeSlug}/visibility`;
+        await this.post(url, {
+            body: JSON.stringify({ visibility }),
+        });
+    }
+    /**
+     * Upload a challenge datapack to Google Cloud Storage.
+     * @param slug - The slug of the challenge.
+     * @param tarballPath - The path to the tarball file.
+     * @returns The upload URL.
+     */
+    async uploadChallengeDatapack(slug, tarballPath) {
+        const uploadUrl = await this.getChallengeUploadUrl(slug);
+        if (!existsSync(tarballPath)) {
+            throw new Error(`Tarball not found at ${tarballPath}`);
+        }
+        const fileBuffer = await fs.readFile(tarballPath);
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/gzip",
+                "Content-Length": fileBuffer.length.toString(),
+            },
+            body: fileBuffer,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to upload datapack: ${response.statusText}`);
+        }
+    }
+    /**
+     * Get the upload URL for a challenge datapack.
+     * @param slug - The slug of the challenge.
+     * @returns The upload URL.
+     */
+    async getChallengeUploadUrl(slug) {
+        const response = await this.get(`challenges/${slug}/datapackUploadUrl`, {}, UploadUrlResponseSchema);
         return response.uploadUrl;
     }
-    async runChallenge(runData, studio = false) {
+    async runChallenge(runData) {
         const url = "jobs";
-        return this.post(studio ? "studio" : "web", url, {
-            body: JSON.stringify(runData),
-        }, RunResponseSchema);
+        const payload = this.isStudio ? runData : { ...runData, jobType: "background" };
+        return this.post(url, {
+            body: JSON.stringify(payload),
+        }, JobResponseSchema);
     }
     async deleteChallenge(challengeId) {
         const url = `challenges/${challengeId}`;
-        await this.delete("web", url);
+        await this.delete(url);
     }
     /**
      * Get the status of a run.
@@ -181,7 +228,7 @@ export class ApiClient {
      */
     async getRunStatus(runId) {
         const url = `runs/${runId}`;
-        return this.get("web", url, {}, RunStatusSchema);
+        return this.get(url, {}, RunStatusSchema);
     }
     /**
      * Add a tag to a run.
@@ -191,8 +238,30 @@ export class ApiClient {
      */
     async tagRun(runId, tag) {
         const url = `runs/${runId}/tag`;
-        await this.post("web", url, {
+        await this.post(url, {
             body: JSON.stringify({ tag }),
         });
     }
+    /**
+     * Get recordings for a specific participant in a run.
+     * @param runId - The ID of the run.
+     * @param participantId - The ID of the participant.
+     * @returns Array of recording metadata.
+     */
+    async getRunRecordings(runId, participantId) {
+        const url = `runs/${runId}/recordings/${participantId}`;
+        const response = await this.get(url, {}, RecordingsListResponseSchema);
+        return response.recordings;
+    }
+    /**
+     * Get a signed download URL for a specific recording.
+     * @param runId - The ID of the run.
+     * @param participantId - The ID of the participant.
+     * @param timestamp - The timestamp of the recording.
+     * @returns Download URL and expiration time.
+     */
+    async getRecordingDownloadUrl(runId, participantId, timestamp) {
+        const url = `runs/${runId}/recordings/${participantId}/downloadUrl?timestamp=${encodeURIComponent(timestamp)}`;
+        return this.get(url, {}, RecordingDownloadUrlResponseSchema);
+    }
 }

package/dist/lib/arguments.d.ts

@@ -2,6 +2,7 @@ import type { Arg } from "@oclif/core/interfaces";
 /**
  * Returns a "challenge slug" argument, and validates it to be a valid challenge slug.
  */
-export declare function getChallengeSlugArgument({ description }: {
+export declare function getChallengeSlugArgument<R extends boolean = true>({ description, required, }: {
     description: string;
-}): Arg<string>;
+    required?: R;
+}): Arg<R extends true ? string : string | undefined>;

package/dist/lib/arguments.js

@@ -3,10 +3,10 @@ const CHALLENGE_SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * Returns a "challenge slug" argument, and validates it to be a valid challenge slug.
  */
-export function getChallengeSlugArgument({ description }) {
-    return Args.string({
+export function getChallengeSlugArgument({ description, required, }) {
+    const arg = Args.string({
         description,
-        required: true,
+        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.`);
@@ -14,4 +14,6 @@ export function getChallengeSlugArgument({ description }) {
             return input;
         },
     });
+    // biome-ignore lint/suspicious/noExplicitAny: Typescript can't handle the conditional "required"
+    return arg;
 }

package/dist/lib/challenge.d.ts

@@ -1,17 +1,10 @@
 import type { ApiClient } from "./api-client.js";
-import type { Config } from "./config.js";
-import { type ChallengeSchemaType } from "./schemas.js";
+import { type ChallengeConfigSchemaType } from "./schemas.js";
 export declare const SOURCE_FOLDER = ".src";
 export declare class Challenge {
-    readonly name: string;
-    private readonly config;
-    constructor(name: string, config: Config);
-    private get kradleChallengesPath();
-    /**
-     * Get the short slug without username prefix
-     * e.g., "florianernst:challenge" -> "challenge"
-     */
-    get shortSlug(): string;
+    readonly shortSlug: string;
+    private readonly kradleChallengesPath;
+    constructor(shortSlug: string, kradleChallengesPath: string);
     /**
      * Get the path to the challenge directory
      */
@@ -47,22 +40,24 @@ export declare class Challenge {
     /**
      * Load the challenge configuration from config.ts
      */
-    loadConfig(): Promise<ChallengeSchemaType>;
+    loadConfig(): Promise<ChallengeConfigSchemaType>;
     /**
-     * Upload the challenge datapack to Google Cloud Storage
+     * 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.
      */
-    upload(apiClient: ApiClient): Promise<void>;
-    buildAndUpload(api: ApiClient): Promise<{
-        config: ChallengeSchemaType;
+    buildAndUpload(api: ApiClient, asPublic: boolean): Promise<{
+        config: ChallengeConfigSchemaType;
         datapackHash: string;
     }>;
     /**
      * Get all local challenges from the challenges directory
      */
-    static getLocalChallenges(): Promise<Record<string, boolean>>;
+    static getLocalChallenges(): Promise<string[]>;
     /**
      * Create a new local challenge folder with challenge.ts template
      * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
      */
-    static createLocal(slug: string, config: Config): Promise<void>;
+    static createLocal(slug: string, kradleChallengesPath: string): Promise<void>;
 }

package/dist/lib/challenge.js

@@ -4,25 +4,15 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import pc from "picocolors";
 import * as tar from "tar";
-import { ChallengeSchema } from "./schemas.js";
+import { ChallengeConfigSchema } from "./schemas.js";
 import { executeNodeCommand, executeTypescriptFile, getStaticResourcePath, readDirSorted } from "./utils.js";
 export const SOURCE_FOLDER = ".src";
 export class Challenge {
-    name;
-    config;
-    constructor(name, config) {
-        this.name = name;
-        this.config = config;
-    }
-    get kradleChallengesPath() {
-        return path.resolve(this.config.KRADLE_CHALLENGES_PATH);
-    }
-    /**
-     * Get the short slug without username prefix
-     * e.g., "florianernst:challenge" -> "challenge"
-     */
-    get shortSlug() {
-        return this.name.includes(":") ? this.name.split(":")[1] : this.name;
+    shortSlug;
+    kradleChallengesPath;
+    constructor(shortSlug, kradleChallengesPath) {
+        this.shortSlug = shortSlug;
+        this.kradleChallengesPath = path.resolve(kradleChallengesPath);
     }
     /**
      * Get the path to the challenge directory
@@ -94,15 +84,27 @@ export class Challenge {
             throw new Error(`Challenge file not found at ${this.challengePath}`);
         }
         try {
-            await executeTypescriptFile(this.challengePath, this.config, { silent });
+            await executeTypescriptFile(this.challengePath, {
+                KRADLE_CHALLENGES_PATH: this.kradleChallengesPath,
+                NAMESPACE: "kradle",
+            }, { silent });
         }
         catch (error) {
             throw new Error(`Failed to build datapack: ${error instanceof Error ? error.message : error}`);
         }
         // @TODO - re-enable once we have a proper build pipeline
         // Copy challenge.ts and config.ts to the src directory
-        await fs.cp(path.join(this.challengeDir, "challenge.ts"), path.join(this.config.KRADLE_CHALLENGES_PATH, this.shortSlug, SOURCE_FOLDER, "challenge.ts"));
-        await fs.cp(path.join(this.challengeDir, "config.ts"), path.join(this.config.KRADLE_CHALLENGES_PATH, this.shortSlug, SOURCE_FOLDER, "config.ts"));
+        await fs.cp(path.join(this.challengeDir, "challenge.ts"), path.join(this.kradleChallengesPath, this.shortSlug, SOURCE_FOLDER, "challenge.ts"));
+        await fs.cp(path.join(this.challengeDir, "config.ts"), path.join(this.kradleChallengesPath, this.shortSlug, SOURCE_FOLDER, "config.ts"));
+        // Create tarball
+        // We need to use the cwd option to make sure the structure of the tarball uses paths relative to the challenge directory
+        await tar.create({
+            "no-mtime": true,
+            file: this.tarballPath, // Output file name
+            gzip: true,
+            cwd: this.datapackPath, // Input directory
+            strict: true,
+        }, ["datapack", SOURCE_FOLDER]);
     }
     /**
      * Load the challenge configuration from config.ts
@@ -118,60 +120,54 @@ export class Challenge {
             "--no-warnings",
             "-e",
             `console.log(JSON.stringify(require("${this.configPath}").config));`,
-        ], this.config);
-        return ChallengeSchema.parse(JSON.parse(stdout));
+        ], {
+            KRADLE_CHALLENGES_PATH: this.kradleChallengesPath,
+            NAMESPACE: "kradle",
+        });
+        return ChallengeConfigSchema.parse(JSON.parse(stdout));
     }
     /**
-     * Upload the challenge datapack to Google Cloud Storage
+     * 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.
      */
-    async upload(apiClient) {
-        // Create tarball
-        // We need to use the cwd option to make sure the structure of the tarball uses paths relative to the challenge directory
-        await tar.create({
-            "no-mtime": true,
-            file: this.tarballPath, // Output file name
-            gzip: true,
-            cwd: this.datapackPath, // Input directory
-            strict: true,
-        }, ["datapack", SOURCE_FOLDER]);
-        const uploadUrl = await apiClient.getChallengeUploadUrl(this);
-        const fileBuffer = await fs.readFile(this.tarballPath);
-        const response = await fetch(uploadUrl, {
-            method: "PUT",
-            headers: {
-                "Content-Type": "application/gzip",
-                "Content-Length": fileBuffer.length.toString(),
-            },
-            body: fileBuffer,
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to upload datapack: ${response.statusText}`);
-        }
-    }
-    async buildAndUpload(api) {
+    async buildAndUpload(api, asPublic) {
         // Ensure challenge exists locally
         if (!this.exists()) {
-            throw new Error(`Challenge "${this.name}" does not exist locally. Make sure both the challenge.ts file and the config.ts file exist.`);
+            throw new Error(`Challenge "${this.shortSlug}" does not exist locally. Make sure both the challenge.ts file and the config.ts file exist.`);
         }
         // Ensure challenge exists in the cloud
-        if (!(await api.challengeExists(this.name))) {
-            console.log(pc.yellow(`Challenge not found in cloud: ${this.name}`));
-            console.log(pc.yellow(`Creating challenge: ${this.name}`));
-            await api.createChallenge(this.name);
+        if (!(await api.challengeExists(this.shortSlug))) {
+            console.log(pc.yellow(`Challenge not found in cloud: ${this.shortSlug}`));
+            console.log(pc.yellow(`Creating challenge: ${this.shortSlug}`));
+            await api.createChallenge(this.shortSlug);
             console.log(pc.green(`✓ Challenge created in cloud`));
         }
-        // Load config
         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;
+        if (cloudChallengeVisibility === "public") {
+            console.log(pc.yellow(`⚠️  Cloud challenge is currently public. Setting its visibility to private...`));
+            await api.updateChallengeVisibility(this.shortSlug, "private");
+            console.log(pc.yellow(`✓  Challenge visibility set to private\n`));
+        }
         // Upload config
         console.log(pc.blue(`>> Uploading config: ${this.shortSlug}`));
-        await api.updateChallenge(this, config);
-        console.log(pc.green(`✓ Config uploaded`));
+        // 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();
         console.log(pc.blue(`>> Uploading datapack: ${this.shortSlug}`));
-        await this.upload(api);
-        console.log(pc.green(`✓ Build & upload complete for ${this.shortSlug}`));
+        await api.uploadChallengeDatapack(this.shortSlug, this.tarballPath);
+        console.log(pc.green(`✓  Build & upload complete for ${this.shortSlug}\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 };
     }
@@ -181,16 +177,16 @@ export class Challenge {
     static async getLocalChallenges() {
         const challengesDir = path.resolve(process.cwd(), "challenges");
         if (!existsSync(challengesDir)) {
-            return {};
+            return [];
         }
         const entries = await readDirSorted(challengesDir);
-        const challenges = {};
+        const challenges = [];
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 // Check if it has a challenge.ts file
                 const challengePath = path.join(challengesDir, entry.name, "challenge.ts");
                 if (existsSync(challengePath)) {
-                    challenges[entry.name] = true;
+                    challenges.push(entry.name);
                 }
             }
         }
@@ -200,8 +196,8 @@ export class Challenge {
      * Create a new local challenge folder with challenge.ts template
      * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
      */
-    static async createLocal(slug, config) {
-        const challenge = new Challenge(slug, config);
+    static async createLocal(slug, kradleChallengesPath) {
+        const challenge = new Challenge(slug, kradleChallengesPath);
         const challengeTemplatePath = getStaticResourcePath("challenge.ts");
         // Create challenge directory
         await fs.mkdir(challenge.challengeDir, { recursive: true });

package/dist/lib/experiment/experimenter.d.ts

@@ -0,0 +1,92 @@
+import type { ApiClient } from "../api-client.js";
+import type { ExperimentMetadata, ExperimentOptions, Manifest, Progress } from "./types.js";
+export declare class Experimenter {
+    private name;
+    private webUrl;
+    private api;
+    experimentDir: string;
+    metadataPath: string;
+    private runner?;
+    private tui?;
+    private currentVersion?;
+    constructor(name: string, webUrl: string, api: ApiClient);
+    /**
+     * Get paths for a specific version
+     */
+    private getVersionPaths;
+    get configPath(): string;
+    /**
+     * Get the current version directory path
+     */
+    getCurrentVersionDir(): string;
+    /**
+     * Check if experiment exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Check if config.ts exists (master config)
+     */
+    configExists(): Promise<boolean>;
+    /**
+     * Load experiment metadata
+     */
+    loadMetadata(): Promise<ExperimentMetadata | null>;
+    /**
+     * Save experiment metadata
+     */
+    saveMetadata(metadata: ExperimentMetadata): Promise<void>;
+    /**
+     * Get the current version number, or -1 if none exists
+     */
+    getCurrentVersionNumber(): Promise<number>;
+    /**
+     * Create a new version
+     */
+    createNewVersion(): Promise<number>;
+    /**
+     * Get or create a version
+     * @param createNew - If true, always create a new version. Otherwise, use current version or create first one if none exists.
+     */
+    getOrCreateVersion(createNew: boolean): Promise<number>;
+    /**
+     * Load manifest from version
+     */
+    loadManifest(version: number): Promise<Manifest>;
+    /**
+     * Load progress from version
+     */
+    loadProgress(version: number): Promise<Progress | null>;
+    /**
+     * Save progress to current version
+     */
+    saveProgress(): Promise<void>;
+    /**
+     * Execute config.ts to generate manifest
+     */
+    generateManifest(configPath: string): Promise<Manifest>;
+    /**
+     * Execute config.ts file and return the manifest
+     */
+    private executeConfigFile;
+    /**
+     * Run the experiment
+     */
+    run(options: ExperimentOptions): Promise<void>;
+    /**
+     * Handle state change from runner
+     */
+    private onRunStateChange;
+    /**
+     * Handle quit request
+     */
+    private handleQuit;
+    /**
+     * Open run in browser
+     */
+    private openRun;
+    /**
+     * Download recordings for a completed run with smart polling
+     * Polls for 90 seconds after run completion (matching pod grace period)
+     */
+    private downloadRecordingsForRun;
+}