@kata.dev/challenge-cli 1.1.2 → 1.2.0

package/README.md

@@ -102,3 +102,54 @@ You can also use environment variables:
 - `CKS_API_BASE_URL` — API URL
 - `CKS_API_TOKEN` — Auth token
 - `CHALLENGE_ARTIFACT_SIGNING_SECRET` — Signing secret for validation
+
+---
+
+## Candidate Workflow
+
+```bash
+# 1. Login with your candidate token
+npx @kata.dev/challenge-cli login --api https://eval.example.com --token <your-token>
+
+# 2. Download starter files for a challenge
+npx @kata.dev/challenge-cli start --slug hello-express
+
+# 3. Solve the challenge (edit files in hello-express/)
+
+# 4. Submit your solution
+npx @kata.dev/challenge-cli submit --slug hello-express
+
+# 5. (Or check score separately)
+npx @kata.dev/challenge-cli score --job <jobId>
+```
+
+### `start`
+
+Download starter files for a published challenge:
+
+```bash
+challenge start --slug my-challenge
+challenge start --slug my-challenge --dir ./workspace
+```
+
+### `submit`
+
+Zip and submit your solution for evaluation:
+
+```bash
+challenge submit --slug my-challenge
+challenge submit --slug my-challenge --dir ./my-challenge
+challenge submit --slug my-challenge --no-poll     # skip auto-polling
+```
+
+By default, `submit` will automatically poll for results after uploading.
+Use `--no-poll` to skip this and just get the job ID.
+
+### `score`
+
+Check the score/status of a previously submitted job:
+
+```bash
+challenge score --job <jobId>
+```
+

package/bin/challenge.js

@@ -10,6 +10,9 @@ import { registerInitCommand } from '../src/commands/init.js';
 import { registerPackCommand } from '../src/commands/pack.js';
 import { registerValidateCommand } from '../src/commands/validate.js';
 import { registerPublishCommand } from '../src/commands/publish.js';
+import { registerStartCommand } from '../src/commands/start.js';
+import { registerSubmitCommand } from '../src/commands/submit.js';
+import { registerScoreCommand } from '../src/commands/score.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -26,6 +29,9 @@ registerInitCommand(program);
 registerPackCommand(program);
 registerValidateCommand(program);
 registerPublishCommand(program);
+registerStartCommand(program);
+registerSubmitCommand(program);
+registerScoreCommand(program);
 
 program.parseAsync(process.argv).catch((err) => {
     console.error(chalk.red('Error:'), err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kata.dev/challenge-cli",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "type": "module",
     "description": "CLI for authoring, packing, validating, and publishing Eval Engine challenges",
     "bin": {
@@ -21,6 +21,7 @@
     ],
     "license": "MIT",
     "dependencies": {
+        "archiver": "^7.0.1",
         "chalk": "^5.4.1",
         "commander": "^13.1.0",
         "ora": "^8.2.0",

package/src/commands/score.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { resolveApiUrl, resolveToken } from '../lib/config.js';
+import { pollJobUntilDone } from '../lib/polling.js';
+
+export function registerScoreCommand(program) {
+    program
+        .command('score')
+        .description('Check the score/status of a submitted evaluation job')
+        .requiredOption('--job <jobId>', 'Job ID from a previous submission')
+        .option('--api <url>', 'API base URL (falls back to config)')
+        .option('--token <token>', 'Auth token (falls back to config)')
+        .action(async (opts) => {
+            const apiBase = resolveApiUrl(opts.api);
+            const token = resolveToken(opts.token);
+            if (!token) {
+                console.error(
+                    chalk.red('Error:') + ' No auth token found.\n' +
+                    'Run ' + chalk.cyan('npx @kata.dev/challenge-cli login') + ' first.'
+                );
+                process.exit(1);
+            }
+
+            const jobId = opts.job;
+            if (!jobId || typeof jobId !== 'string' || jobId.trim() === '') {
+                console.error(chalk.red('Error:') + ' --job <jobId> is required.');
+                process.exit(1);
+            }
+
+            console.log(chalk.bold(`\nChecking score for job ${chalk.cyan(jobId)}\n`));
+
+            await pollJobUntilDone({ apiBase, token, jobId });
+        });
+}

package/src/commands/start.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { resolveApiUrl, resolveToken } from '../lib/config.js';
+import { requestJson, fetchWithTimeout } from '../lib/http.js';
+import { assertSlug } from '../lib/helpers.js';
+import tar from 'tar';
+
+export function registerStartCommand(program) {
+    program
+        .command('start')
+        .description('Download starter files for a challenge')
+        .requiredOption('--slug <slug>', 'Challenge slug')
+        .option('--dir <path>', 'Directory to extract into (defaults to ./<slug>)')
+        .option('--api <url>', 'API base URL (falls back to config)')
+        .option('--token <token>', 'Auth token (falls back to config)')
+        .action(async (opts) => {
+            const slug = opts.slug;
+            assertSlug(slug);
+
+            const apiBase = resolveApiUrl(opts.api);
+            const token = resolveToken(opts.token);
+            if (!token) {
+                console.error(
+                    chalk.red('Error:') + ' No auth token found.\n' +
+                    'Run ' + chalk.cyan('npx @kata.dev/challenge-cli login') + ' first.'
+                );
+                process.exit(1);
+            }
+
+            const targetDir = path.resolve(opts.dir || `./${slug}`);
+
+            console.log(chalk.bold(`\nDownloading starter for ${chalk.cyan(slug)}\n`));
+
+            // Step 1: Get presigned download URL
+            let spinner = ora('Fetching starter download URL…').start();
+            let downloadUrl;
+            try {
+                const result = await requestJson(`${apiBase}/challenges/${slug}/starter`, {
+                    method: 'GET',
+                    token,
+                });
+                downloadUrl = result.downloadUrl;
+                spinner.succeed('Starter URL resolved');
+            } catch (err) {
+                spinner.fail('Failed to get starter URL');
+                throw err;
+            }
+
+            // Step 2: Download the tar.gz
+            spinner = ora('Downloading starter archive…').start();
+            let buffer;
+            try {
+                const response = await fetchWithTimeout(downloadUrl);
+                if (!response.ok) {
+                    throw new Error(`Download failed: HTTP ${response.status}`);
+                }
+                const arrayBuffer = await response.arrayBuffer();
+                buffer = Buffer.from(arrayBuffer);
+                spinner.succeed(`Downloaded (${(buffer.length / 1024).toFixed(1)} KB)`);
+            } catch (err) {
+                spinner.fail('Download failed');
+                throw err;
+            }
+
+            // Step 3: Extract
+            spinner = ora(`Extracting to ${chalk.dim(targetDir)}…`).start();
+            try {
+                fs.mkdirSync(targetDir, { recursive: true });
+
+                // Write temp archive and extract
+                const tmpPath = path.join(targetDir, '.starter-download.tar.gz');
+                fs.writeFileSync(tmpPath, buffer);
+                await tar.x({
+                    file: tmpPath,
+                    cwd: targetDir,
+                    strip: 0,
+                });
+                fs.unlinkSync(tmpPath);
+
+                spinner.succeed('Extracted starter files');
+            } catch (err) {
+                spinner.fail('Extraction failed');
+                throw err;
+            }
+
+            console.log();
+            console.log(chalk.green('✔') + ` Starter files ready in ${chalk.cyan(targetDir)}`);
+            console.log();
+            console.log(chalk.dim('Next steps:'));
+            console.log(`  1. ${chalk.dim('cd')} ${slug}`);
+            console.log(`  2. Solve the challenge`);
+            console.log(`  3. ${chalk.cyan(`npx @kata.dev/challenge-cli submit --slug ${slug} --dir ./${slug}`)}`);
+            console.log();
+        });
+}

package/src/commands/submit.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createWriteStream } from 'node:fs';
+import chalk from 'chalk';
+import ora from 'ora';
+import archiver from 'archiver';
+import { resolveApiUrl, resolveToken } from '../lib/config.js';
+import { fetchWithTimeout } from '../lib/http.js';
+import { assertSlug } from '../lib/helpers.js';
+import { pollJobUntilDone } from '../lib/polling.js';
+
+function zipDirectory(sourceDir) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const archive = archiver('zip', { zlib: { level: 9 } });
+
+        archive.on('data', (chunk) => chunks.push(chunk));
+        archive.on('end', () => resolve(Buffer.concat(chunks)));
+        archive.on('error', (err) => reject(err));
+
+        archive.directory(sourceDir, false);
+        archive.finalize();
+    });
+}
+
+export function registerSubmitCommand(program) {
+    program
+        .command('submit')
+        .description('Zip and submit your solution for evaluation')
+        .requiredOption('--slug <slug>', 'Challenge slug')
+        .option('--dir <path>', 'Solution directory (defaults to ./<slug>)')
+        .option('--api <url>', 'API base URL (falls back to config)')
+        .option('--token <token>', 'Auth token (falls back to config)')
+        .option('--no-poll', 'Skip automatic polling for results')
+        .action(async (opts) => {
+            const slug = opts.slug;
+            assertSlug(slug);
+
+            const apiBase = resolveApiUrl(opts.api);
+            const token = resolveToken(opts.token);
+            if (!token) {
+                console.error(
+                    chalk.red('Error:') + ' No auth token found.\n' +
+                    'Run ' + chalk.cyan('npx @kata.dev/challenge-cli login') + ' first.'
+                );
+                process.exit(1);
+            }
+
+            const solutionDir = path.resolve(opts.dir || `./${slug}`);
+
+            if (!fs.existsSync(solutionDir)) {
+                console.error(chalk.red('Error:') + ` Directory not found: ${solutionDir}`);
+                process.exit(1);
+            }
+
+            console.log(chalk.bold(`\nSubmitting solution for ${chalk.cyan(slug)}\n`));
+
+            // Step 1: Zip the solution
+            let spinner = ora('Zipping solution…').start();
+            let zipBuffer;
+            try {
+                zipBuffer = await zipDirectory(solutionDir);
+                spinner.succeed(`Zipped (${(zipBuffer.length / 1024).toFixed(1)} KB)`);
+            } catch (err) {
+                spinner.fail('Failed to zip solution');
+                throw err;
+            }
+
+            // Step 2: Upload via POST /evaluate
+            spinner = ora('Uploading submission…').start();
+            let jobId;
+            try {
+                const formData = new FormData();
+                formData.append('challengeId', slug);
+                formData.append(
+                    'submission',
+                    new Blob([zipBuffer], { type: 'application/zip' }),
+                    `${slug}-submission.zip`
+                );
+
+                const response = await fetchWithTimeout(`${apiBase}/evaluate`, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${token}`,
+                    },
+                    body: formData,
+                });
+
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    let errorMsg;
+                    try {
+                        errorMsg = JSON.parse(errorBody).error || errorBody;
+                    } catch {
+                        errorMsg = errorBody;
+                    }
+                    throw new Error(`Submission failed (${response.status}): ${errorMsg}`);
+                }
+
+                const result = await response.json();
+                jobId = result.jobId;
+                spinner.succeed(`Submitted — Job ID: ${chalk.cyan(jobId)}`);
+            } catch (err) {
+                spinner.fail('Submission failed');
+                throw err;
+            }
+
+            console.log();
+
+            // Step 3: Auto-poll if enabled
+            if (opts.poll !== false) {
+                await pollJobUntilDone({ apiBase, token, jobId });
+            } else {
+                console.log(chalk.dim('Check your score with:'));
+                console.log(`  ${chalk.cyan(`npx @kata.dev/challenge-cli score --job ${jobId}`)}`);
+                console.log();
+            }
+        });
+}

package/src/lib/polling.js

@@ -0,0 +1,111 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { requestJson } from './http.js';
+
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'error', 'timed_out']);
+const POLL_INTERVAL_MS = 3000;
+const MAX_POLLS = 200;
+
+export async function pollJobUntilDone({ apiBase, token, jobId }) {
+    const spinner = ora('Waiting for evaluation results…').start();
+
+    let polls = 0;
+    let job = null;
+
+    while (polls < MAX_POLLS) {
+        try {
+            job = await requestJson(`${apiBase}/jobs/${jobId}`, {
+                method: 'GET',
+                token,
+            });
+        } catch (err) {
+            spinner.fail('Failed to poll job status');
+            throw err;
+        }
+
+        if (TERMINAL_STATUSES.has(job.status)) {
+            break;
+        }
+
+        spinner.text = `Status: ${chalk.yellow(job.status)} — polling… (${polls + 1})`;
+        polls += 1;
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+
+    spinner.stop();
+
+    if (!job || !TERMINAL_STATUSES.has(job.status)) {
+        console.log(chalk.yellow('⚠') + ' Timed out waiting for results.');
+        console.log(chalk.dim('Check again with:'));
+        console.log(`  ${chalk.cyan(`npx @kata.dev/challenge-cli score --job ${jobId}`)}`);
+        return;
+    }
+
+    // Display result
+    console.log(formatResult(job, jobId));
+}
+
+function formatResult(job, jobId) {
+    const lines = [];
+
+    const statusIcon = job.status === 'completed' ? chalk.green('✔') : chalk.red('✘');
+    const statusLabel = job.status === 'completed'
+        ? chalk.green.bold('PASSED')
+        : chalk.red.bold(job.status.toUpperCase());
+
+    lines.push(`${statusIcon} Result: ${statusLabel}`);
+    lines.push('');
+
+    if (job.resultJson) {
+        const result = typeof job.resultJson === 'string'
+            ? JSON.parse(job.resultJson)
+            : job.resultJson;
+
+        if (result.summary) {
+            lines.push(chalk.bold('Summary:'));
+            lines.push(`  ${result.summary}`);
+            lines.push('');
+        }
+
+        if (result.passed !== undefined && result.total !== undefined) {
+            const scoreColor = result.passed === result.total ? chalk.green : chalk.yellow;
+            lines.push(
+                chalk.bold('Score: ') +
+                scoreColor(`${result.passed}/${result.total} tests passed`)
+            );
+            lines.push('');
+        }
+
+        if (result.score !== undefined) {
+            lines.push(chalk.bold('Score: ') + chalk.cyan(result.score));
+            lines.push('');
+        }
+
+        if (Array.isArray(result.testResults)) {
+            lines.push(chalk.bold('Test Results:'));
+            for (const test of result.testResults) {
+                const icon = test.status === 'passed' ? chalk.green('  ✔') : chalk.red('  ✘');
+                const name = test.name || test.title || 'unnamed';
+                lines.push(`${icon} ${name}`);
+                if (test.status !== 'passed' && test.message) {
+                    lines.push(chalk.dim(`    ${test.message}`));
+                }
+            }
+            lines.push('');
+        }
+    }
+
+    if (job.errorCode) {
+        lines.push(chalk.red(`Error: ${job.errorCode}`));
+        if (job.errorMessage) {
+            lines.push(chalk.dim(`  ${job.errorMessage}`));
+        }
+        lines.push('');
+    }
+
+    lines.push(chalk.dim(`Job ID: ${jobId}`));
+    lines.push(chalk.dim(`View logs: npx @kata.dev/challenge-cli score --job ${jobId}`));
+    lines.push('');
+
+    return lines.join('\n');
+}