@kata.dev/challenge-cli 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# @kata.dev/challenge-cli
+
+CLI for authoring, packing, validating, and publishing Eval Engine challenges.
+
+## Install
+
+```bash
+npx @kata.dev/challenge-cli --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @kata.dev/challenge-cli
+```
+
+## Quick Start
+
+```bash
+# 1. Save your API credentials
+npx @kata.dev/challenge-cli login --api https://eval.example.com --token <your-token>
+
+# 2. Scaffold a new challenge
+npx @kata.dev/challenge-cli init --slug hello-express
+
+# 3. Author your challenge (edit files in hello-express/)
+
+# 4. Pack artifacts
+npx @kata.dev/challenge-cli pack --dir ./hello-express
+
+# 5. Validate locally
+npx @kata.dev/challenge-cli validate --manifest ./hello-express/dist/cks-manifest.json
+
+# 6. Publish to the API
+npx @kata.dev/challenge-cli publish --manifest ./hello-express/dist/cks-manifest.json
+```
+
+## Commands
+
+### `login`
+
+Save API URL and authentication token to `~/.challengerc.json`:
+
+```bash
+challenge login --api https://eval.example.com --token <token>
+challenge login --api https://eval.example.com --token <token> --signing-secret <secret>
+```
+
+### `init`
+
+Scaffold a new challenge directory:
+
+```bash
+challenge init --slug my-challenge
+challenge init --slug my-challenge --dir ./challenges
+challenge init   # interactive mode (prompts for slug)
+```
+
+### `pack`
+
+Pack challenge artifacts into uploadable bundles:
+
+```bash
+challenge pack --dir ./my-challenge
+challenge pack --dir ./my-challenge --out ./my-challenge/dist --runtime-mode auto
+```
+
+Runtime modes:
+- `auto` (default) — Builds `node_modules` from `artifacts/runtime_manifest/package.json`
+- `manual` — Uses `artifacts/runtime_deps/` directly
+
+### `validate`
+
+Validate packed artifacts locally:
+
+```bash
+challenge validate --manifest ./my-challenge/dist/cks-manifest.json
+```
+
+### `publish`
+
+Publish a challenge to the Eval Engine API:
+
+```bash
+challenge publish --manifest ./my-challenge/dist/cks-manifest.json
+challenge publish --manifest ./my-challenge/dist/cks-manifest.json --api https://eval.example.com --token <token>
+```
+
+## Configuration
+
+Credentials are stored in `~/.challengerc.json`:
+
+```json
+{
+  "apiUrl": "https://eval.example.com",
+  "token": "eyJ...",
+  "signingSecret": "your-signing-secret"
+}
+```
+
+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

package/bin/challenge.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { registerLoginCommand } from '../src/commands/login.js';
+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';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+    .name('challenge')
+    .description('CLI for authoring, packing, validating, and publishing Eval Engine challenges')
+    .version(pkg.version);
+
+registerLoginCommand(program);
+registerInitCommand(program);
+registerPackCommand(program);
+registerValidateCommand(program);
+registerPublishCommand(program);
+
+program.parseAsync(process.argv).catch((err) => {
+    console.error(chalk.red('Error:'), err.message);
+    if (process.env.DEBUG) {
+        console.error(err.stack);
+    }
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@kata.dev/challenge-cli",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "CLI for authoring, packing, validating, and publishing Eval Engine challenges",
+    "bin": {
+        "challenge": "bin/challenge.js"
+    },
+    "files": [
+        "bin/",
+        "src/"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "keywords": [
+        "eval-engine",
+        "challenge",
+        "cli",
+        "authoring"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "chalk": "^5.4.1",
+        "commander": "^13.1.0",
+        "ora": "^8.2.0",
+        "prompts": "^2.4.2",
+        "tar": "^7.4.3"
+    }
+}

package/src/commands/init.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import prompts from 'prompts';
+import { ARTIFACT_TYPES } from '../lib/artifacts.js';
+import { assertSlug, ensureDir, writeJson } from '../lib/helpers.js';
+
+async function resolveSlug(flagSlug) {
+    if (flagSlug) return flagSlug;
+
+    const response = await prompts({
+        type: 'text',
+        name: 'slug',
+        message: 'Challenge slug (lowercase, dashes only):',
+        validate: (v) => /^[a-z0-9-]+$/.test(v) || 'Must be lowercase alphanumeric with dashes',
+    });
+
+    if (!response.slug) {
+        throw new Error('Challenge slug is required.');
+    }
+    return response.slug;
+}
+
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .description('Scaffold a new challenge authoring directory')
+        .option('--slug <slug>', 'Challenge slug (lowercase, dashes)')
+        .option('--dir <baseDir>', 'Parent directory to create the challenge in', process.cwd())
+        .action(async (opts) => {
+            const slug = await resolveSlug(opts.slug);
+            assertSlug(slug);
+
+            const baseDir = path.resolve(opts.dir, slug);
+
+            if (fs.existsSync(baseDir)) {
+                throw new Error(`Directory already exists: ${baseDir}`);
+            }
+
+            const artifactRoots = {
+                tests: path.join(baseDir, 'artifacts', 'tests'),
+                starter: path.join(baseDir, 'artifacts', 'starter'),
+                runtime_deps: path.join(baseDir, 'artifacts', 'runtime_deps'),
+                runtime_manifest: path.join(baseDir, 'artifacts', 'runtime_manifest'),
+            };
+
+            ensureDir(baseDir);
+            for (const dir of Object.values(artifactRoots)) {
+                ensureDir(dir);
+            }
+
+            // challenge.json
+            writeJson(path.join(baseDir, 'challenge.json'), {
+                slug,
+                title: slug,
+                owner: 'team-evals',
+                version: 1,
+                runner: 'express-supertest',
+                entry: 'src/app.js',
+                timeoutSec: 10,
+                allowedDependencies: ['express@5.2.1'],
+                allowedPaths: ['src/'],
+                requiredFiles: ['src/app.js'],
+                description: 'Describe challenge behavior and grading expectations.',
+            });
+
+            // Example test
+            const exampleTestPath = path.join(artifactRoots.tests, 'example.test.js');
+            fs.writeFileSync(
+                exampleTestPath,
+                `const request = require('supertest');
+const app = require('./src/app');
+
+describe('GET /', () => {
+  it('should respond with 200', async () => {
+    const res = await request(app).get('/');
+    expect(res.status).toBe(200);
+  });
+});
+`,
+                'utf8'
+            );
+
+            // Starter code
+            const starterDir = path.join(artifactRoots.starter, 'src');
+            ensureDir(starterDir);
+            fs.writeFileSync(
+                path.join(starterDir, 'app.js'),
+                `const express = require('express');
+const app = express();
+
+// TODO: Implement your routes here
+
+module.exports = app;
+`,
+                'utf8'
+            );
+
+            // Runtime manifest
+            writeJson(path.join(artifactRoots.runtime_manifest, 'package.json'), {
+                name: `${slug}-runtime-deps`,
+                private: true,
+                version: '1.0.0',
+                description: 'Dependencies needed by hidden challenge tests at runtime.',
+                dependencies: {},
+            });
+
+            // README files
+            for (const type of ARTIFACT_TYPES) {
+                const artifactDir = artifactRoots[type];
+                if (!artifactDir) continue;
+                const readme = path.join(artifactDir, 'README.md');
+                if (!fs.existsSync(readme)) {
+                    fs.writeFileSync(
+                        readme,
+                        `# ${type}\n\nPlace files for the \`${type}\` artifact in this folder.\n`,
+                        'utf8'
+                    );
+                }
+            }
+
+            console.log();
+            console.log(chalk.green('✔') + ` Challenge scaffolded at ${chalk.bold(baseDir)}`);
+            console.log();
+            console.log(chalk.dim('  Structure:'));
+            console.log(chalk.dim(`    ${slug}/`));
+            console.log(chalk.dim('    ├── challenge.json'));
+            console.log(chalk.dim('    └── artifacts/'));
+            console.log(chalk.dim('        ├── tests/'));
+            console.log(chalk.dim('        ├── starter/'));
+            console.log(chalk.dim('        ├── runtime_deps/'));
+            console.log(chalk.dim('        └── runtime_manifest/'));
+            console.log();
+            console.log(`  Next: edit ${chalk.cyan('challenge.json')} and add tests, then run:`);
+            console.log(`    ${chalk.cyan(`npx @kata.dev/challenge-cli pack --dir ./${slug}`)}`);
+        });
+}

package/src/commands/login.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { saveConfig, loadConfig } from '../lib/config.js';
+
+export function registerLoginCommand(program) {
+    program
+        .command('login')
+        .description('Save API credentials to ~/.challengerc.json')
+        .requiredOption('--api <url>', 'Eval Engine API base URL')
+        .requiredOption('--token <token>', 'Authentication token (JWT)')
+        .option('--signing-secret <secret>', 'Challenge artifact signing secret (optional, for local validation)')
+        .action(async (opts) => {
+            const existing = loadConfig();
+
+            const config = {
+                ...existing,
+                apiUrl: opts.api.replace(/\/$/, ''),
+                token: opts.token,
+            };
+
+            if (opts.signingSecret) {
+                config.signingSecret = opts.signingSecret;
+            }
+
+            const configPath = saveConfig(config);
+
+            console.log(chalk.green('✔') + ' Credentials saved to ' + chalk.dim(configPath));
+            console.log('  API:   ' + chalk.cyan(config.apiUrl));
+            console.log('  Token: ' + chalk.dim(config.token.slice(0, 20) + '…'));
+            if (config.signingSecret) {
+                console.log('  Signing secret: ' + chalk.dim('configured'));
+            }
+        });
+}

package/src/commands/pack.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { REQUIRED_ARTIFACT_TYPES, packArtifact } from '../lib/artifacts.js';
+import {
+    readJson,
+    writeJson,
+    assertSlug,
+    assertPinnedAllowedDependencies,
+    resolveRuntimeMode,
+} from '../lib/helpers.js';
+import { resolveRuntimeDepsSourceDir } from '../lib/runtime-deps.js';
+import { resolveSigningSecret } from '../lib/config.js';
+
+export function registerPackCommand(program) {
+    program
+        .command('pack')
+        .description('Pack challenge artifacts into uploadable bundles')
+        .requiredOption('--dir <challengeDir>', 'Path to the challenge directory')
+        .option('--out <outDir>', 'Output directory (defaults to <challengeDir>/dist)')
+        .option('--runtime-mode <mode>', 'Runtime deps mode: auto (default) or manual', 'auto')
+        .option('--signing-secret <secret>', 'Artifact signing secret (falls back to config)')
+        .action(async (opts) => {
+            const challengeDir = path.resolve(opts.dir);
+            const outDir = path.resolve(opts.out || path.join(challengeDir, 'dist'));
+            const runtimeMode = resolveRuntimeMode(opts.runtimeMode);
+
+            const signingSecret = resolveSigningSecret(opts.signingSecret);
+            if (!signingSecret) {
+                throw new Error(
+                    'Signing secret is required. Set it via --signing-secret, CHALLENGE_ARTIFACT_SIGNING_SECRET env var, or run "challenge login --signing-secret <secret>".'
+                );
+            }
+
+            const challengeJsonPath = path.join(challengeDir, 'challenge.json');
+            if (!fs.existsSync(challengeJsonPath)) {
+                throw new Error(`challenge.json not found: ${challengeJsonPath}`);
+            }
+
+            const metadata = readJson(challengeJsonPath);
+            assertSlug(metadata.slug);
+            assertPinnedAllowedDependencies(metadata.allowedDependencies);
+
+            console.log(chalk.bold(`\nPacking ${metadata.slug}@${metadata.version}\n`));
+
+            const artifacts = {};
+            for (const type of REQUIRED_ARTIFACT_TYPES) {
+                const spinner = ora(`Packing ${type}…`).start();
+
+                try {
+                    const sourceDir =
+                        type === 'runtime_deps'
+                            ? await resolveRuntimeDepsSourceDir({
+                                challengeDir,
+                                runtimeMode,
+                                log: (msg) => { spinner.text = msg; },
+                            })
+                            : path.join(challengeDir, 'artifacts', type);
+
+                    if (!fs.existsSync(sourceDir)) {
+                        throw new Error(`Missing artifact source: ${sourceDir}`);
+                    }
+
+                    const outputFile = path.join(outDir, `${type}.tar.gz`);
+                    const packed = await packArtifact(sourceDir, outputFile, signingSecret);
+
+                    artifacts[type] = {
+                        sha256: packed.sha256,
+                        signature: packed.signature,
+                        sizeBytes: packed.sizeBytes,
+                        file: path.basename(outputFile),
+                    };
+
+                    const sizeKb = (packed.sizeBytes / 1024).toFixed(1);
+                    spinner.succeed(`${type}  ${chalk.dim(`${sizeKb} KB  sha256:${packed.sha256.slice(0, 12)}…`)}`);
+                } catch (err) {
+                    spinner.fail(`${type} failed`);
+                    throw err;
+                }
+            }
+
+            const manifest = {
+                cksVersion: '1',
+                generatedAt: new Date().toISOString(),
+                metadata,
+                artifacts,
+            };
+
+            const manifestPath = path.join(outDir, 'cks-manifest.json');
+            writeJson(manifestPath, manifest);
+
+            console.log();
+            console.log(chalk.green('✔') + ` Manifest: ${chalk.cyan(manifestPath)}`);
+            console.log();
+            console.log('  Next steps:');
+            console.log(`    ${chalk.cyan(`npx @kata.dev/challenge-cli validate --manifest ${path.relative(process.cwd(), manifestPath)}`)}`);
+            console.log(`    ${chalk.cyan(`npx @kata.dev/challenge-cli publish --manifest ${path.relative(process.cwd(), manifestPath)}`)}`);
+        });
+}

package/src/commands/publish.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { REQUIRED_ARTIFACT_TYPES } from '../lib/artifacts.js';
+import { readJson, assertSlug, assertPinnedAllowedDependencies } from '../lib/helpers.js';
+import { fetchWithTimeout, requestJson } from '../lib/http.js';
+import { resolveApiUrl, resolveToken } from '../lib/config.js';
+
+async function ensureChallengeExists(apiBase, token, metadata) {
+    try {
+        await requestJson(`${apiBase}/admin/challenges`, {
+            method: 'POST',
+            token,
+            body: {
+                slug: metadata.slug,
+                title: metadata.title || metadata.slug,
+                owner: metadata.owner || 'team-evals',
+            },
+        });
+    } catch (err) {
+        if (err.status !== 409) throw err;
+        // 409 = already exists, that's fine
+    }
+}
+
+async function uploadArtifacts({ apiBase, token, versionId, manifest, manifestPath, onProgress }) {
+    for (const type of REQUIRED_ARTIFACT_TYPES) {
+        onProgress(type, 'uploading');
+
+        const artifact = manifest.artifacts[type];
+        const artifactPath = path.resolve(path.dirname(manifestPath), artifact.file);
+
+        const uploadTicket = await requestJson(
+            `${apiBase}/admin/challenge-versions/${versionId}/artifacts/${type}/presign-upload`,
+            {
+                method: 'POST',
+                token,
+                body: {
+                    sha256: artifact.sha256,
+                    sizeBytes: artifact.sizeBytes,
+                },
+            }
+        );
+
+        const uploadResponse = await fetchWithTimeout(uploadTicket.upload.url, {
+            method: uploadTicket.upload.method || 'PUT',
+            headers: uploadTicket.upload.headers || {
+                'content-type': 'application/gzip',
+            },
+            body: fs.readFileSync(artifactPath),
+        });
+
+        if (!uploadResponse.ok) {
+            throw new Error(`Artifact upload failed for ${type}: HTTP ${uploadResponse.status}`);
+        }
+
+        onProgress(type, 'done');
+    }
+}
+
+export function registerPublishCommand(program) {
+    program
+        .command('publish')
+        .description('Publish a challenge to the Eval Engine API')
+        .requiredOption('--manifest <path>', 'Path to cks-manifest.json')
+        .option('--api <url>', 'API base URL (falls back to config)')
+        .option('--token <token>', 'Auth token (falls back to config)')
+        .action(async (opts) => {
+            const manifestPath = path.resolve(opts.manifest);
+            const apiBase = resolveApiUrl(opts.api);
+            const token = resolveToken(opts.token);
+
+            const manifest = readJson(manifestPath);
+            const metadata = manifest.metadata || {};
+            assertSlug(metadata.slug);
+            assertPinnedAllowedDependencies(metadata.allowedDependencies);
+
+            console.log(chalk.bold(`\nPublishing ${metadata.slug}@${metadata.version}\n`));
+            console.log(chalk.dim(`  API: ${apiBase}\n`));
+
+            // Step 1: Ensure challenge exists
+            let spinner = ora('Creating challenge (or confirming exists)…').start();
+            try {
+                await ensureChallengeExists(apiBase, token, metadata);
+                spinner.succeed('Challenge exists');
+            } catch (err) {
+                spinner.fail('Failed to create challenge');
+                throw err;
+            }
+
+            // Step 2: Create version
+            spinner = ora('Creating version…').start();
+            let version;
+            try {
+                version = await requestJson(`${apiBase}/admin/challenges/${metadata.slug}/versions`, {
+                    method: 'POST',
+                    token,
+                    body: {
+                        version: metadata.version,
+                        runner: metadata.runner,
+                        entry: metadata.entry,
+                        timeoutSec: metadata.timeoutSec,
+                        allowedDependencies: metadata.allowedDependencies,
+                        allowedPaths: metadata.allowedPaths,
+                        requiredFiles: metadata.requiredFiles,
+                        description: metadata.description,
+                    },
+                });
+                spinner.succeed(`Version created (id: ${chalk.dim(version.id)})`);
+            } catch (err) {
+                spinner.fail('Failed to create version');
+                throw err;
+            }
+
+            // Step 3: Upload artifacts
+            spinner = ora('Uploading artifacts…').start();
+            try {
+                await uploadArtifacts({
+                    apiBase,
+                    token,
+                    versionId: version.id,
+                    manifest,
+                    manifestPath,
+                    onProgress: (type, status) => {
+                        if (status === 'uploading') {
+                            spinner.text = `Uploading ${type}…`;
+                        }
+                    },
+                });
+                spinner.succeed('Artifacts uploaded');
+            } catch (err) {
+                spinner.fail('Upload failed');
+                throw err;
+            }
+
+            // Step 4: Validate
+            spinner = ora('Server-side validation…').start();
+            try {
+                await requestJson(`${apiBase}/admin/challenge-versions/${version.id}/validate`, {
+                    method: 'POST',
+                    token,
+                });
+                spinner.succeed('Validation passed');
+            } catch (err) {
+                spinner.fail('Validation failed');
+                throw err;
+            }
+
+            // Step 5: Publish
+            spinner = ora('Publishing…').start();
+            try {
+                const published = await requestJson(`${apiBase}/admin/challenge-versions/${version.id}/publish`, {
+                    method: 'POST',
+                    token,
+                });
+                spinner.succeed('Published');
+
+                console.log();
+                console.log(
+                    chalk.green('✔') +
+                    ` ${chalk.bold(metadata.slug)}@${metadata.version} is now live!`
+                );
+                console.log(chalk.dim(`  challengeVersionId: ${published.challengeVersionId}`));
+            } catch (err) {
+                spinner.fail('Publish failed');
+                throw err;
+            }
+        });
+}

package/src/commands/validate.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import {
+    REQUIRED_ARTIFACT_TYPES,
+    computeSha256Hex,
+    signSha256Hex,
+    validateTarGzBuffer,
+} from '../lib/artifacts.js';
+import { readJson } from '../lib/helpers.js';
+import { resolveSigningSecret } from '../lib/config.js';
+
+export function registerValidateCommand(program) {
+    program
+        .command('validate')
+        .description('Validate packed artifacts locally')
+        .requiredOption('--manifest <path>', 'Path to cks-manifest.json')
+        .option('--signing-secret <secret>', 'Artifact signing secret (falls back to config)')
+        .action(async (opts) => {
+            const manifestPath = path.resolve(opts.manifest);
+            const signingSecret = resolveSigningSecret(opts.signingSecret);
+
+            if (!signingSecret) {
+                throw new Error(
+                    'Signing secret is required for validation. Set it via --signing-secret, CHALLENGE_ARTIFACT_SIGNING_SECRET env var, or run "challenge login --signing-secret <secret>".'
+                );
+            }
+
+            const manifest = readJson(manifestPath);
+            const slug = manifest.metadata?.slug || 'unknown';
+
+            console.log(chalk.bold(`\nValidating ${slug}@${manifest.metadata?.version || '?'}\n`));
+
+            for (const type of REQUIRED_ARTIFACT_TYPES) {
+                const spinner = ora(`Checking ${type}…`).start();
+
+                const artifact = manifest.artifacts && manifest.artifacts[type];
+                if (!artifact) {
+                    spinner.fail(`${type}: missing from manifest`);
+                    throw new Error(`Manifest missing artifact: ${type}`);
+                }
+
+                const artifactPath = path.resolve(path.dirname(manifestPath), artifact.file);
+                if (!fs.existsSync(artifactPath)) {
+                    spinner.fail(`${type}: file not found`);
+                    throw new Error(`Artifact file does not exist: ${artifactPath}`);
+                }
+
+                const buffer = fs.readFileSync(artifactPath);
+
+                // Verify SHA-256
+                const actualSha = computeSha256Hex(buffer);
+                if (actualSha !== artifact.sha256) {
+                    spinner.fail(`${type}: SHA-256 mismatch`);
+                    throw new Error(`SHA mismatch for ${type}. expected=${artifact.sha256} actual=${actualSha}`);
+                }
+
+                // Verify HMAC signature
+                const actualSig = signSha256Hex(actualSha, signingSecret);
+                if (actualSig !== artifact.signature) {
+                    spinner.fail(`${type}: signature mismatch`);
+                    throw new Error(`Signature mismatch for ${type}. expected=${artifact.signature} actual=${actualSig}`);
+                }
+
+                // Validate tar contents
+                spinner.text = `Validating ${type} tar contents…`;
+                const { entryCount, totalSize } = await validateTarGzBuffer({ buffer });
+
+                const sizeKb = (totalSize / 1024).toFixed(1);
+                spinner.succeed(`${type}  ${chalk.dim(`${entryCount} entries, ${sizeKb} KB extracted`)}`);
+            }
+
+            console.log();
+            console.log(chalk.green('✔') + ' All artifacts validated successfully');
+        });
+}

package/src/lib/artifacts.js

@@ -0,0 +1,123 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { create as tarCreate, list as tarList } from 'tar';
+
+export const ARTIFACT_TYPES = ['tests', 'starter', 'runtime_deps'];
+export const REQUIRED_ARTIFACT_TYPES = ['tests', 'starter', 'runtime_deps'];
+
+export function computeSha256Hex(buffer) {
+    if (!Buffer.isBuffer(buffer)) {
+        throw new Error('Buffer required to compute SHA-256.');
+    }
+    return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+export function signSha256Hex(sha256Hex, secret) {
+    if (!sha256Hex || typeof sha256Hex !== 'string') {
+        throw new Error('sha256Hex is required to compute signature.');
+    }
+    if (!secret || typeof secret !== 'string') {
+        throw new Error('Signing secret is required to compute signature.');
+    }
+    return crypto.createHmac('sha256', secret).update(sha256Hex).digest('hex');
+}
+
+export function assertSafeTarPath(entryPath) {
+    const normalized = String(entryPath || '').replace(/\\/g, '/');
+    if (!normalized) {
+        throw new Error('Invalid tar entry path: empty path.');
+    }
+    if (normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized)) {
+        throw new Error(`Unsafe tar entry path: ${entryPath}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.includes('..')) {
+        throw new Error(`Unsafe tar entry path traversal: ${entryPath}`);
+    }
+    const cleaned = path.posix.normalize(normalized);
+    if (cleaned === '..' || cleaned.startsWith('../') || cleaned.includes('/../')) {
+        throw new Error(`Unsafe tar entry path traversal: ${entryPath}`);
+    }
+}
+
+async function withTempArchive(buffer, fn) {
+    const tmpRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'challenge-cli-artifact-'));
+    const archivePath = path.join(tmpRoot, 'artifact.tar.gz');
+    try {
+        await fs.promises.writeFile(archivePath, buffer);
+        return await fn(archivePath, tmpRoot);
+    } finally {
+        await fs.promises.rm(tmpRoot, { recursive: true, force: true });
+    }
+}
+
+export async function validateTarGzBuffer({ buffer, maxEntries = 2000, maxExtractedBytes = 104857600 }) {
+    if (!Buffer.isBuffer(buffer)) {
+        throw new Error('Artifact tar validation requires a Buffer.');
+    }
+
+    let entryCount = 0;
+    let totalSize = 0;
+    let validationError = null;
+
+    await withTempArchive(buffer, async (archivePath) => {
+        await tarList({
+            file: archivePath,
+            strict: true,
+            onentry: (entry) => {
+                if (validationError) return;
+                try {
+                    entryCount += 1;
+                    if (entryCount > maxEntries) {
+                        throw new Error(`Tar entry count exceeds maximum (${maxEntries}).`);
+                    }
+                    assertSafeTarPath(entry.path);
+                    if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
+                        throw new Error(`Symlink/hardlink entries are not allowed: ${entry.path}`);
+                    }
+                    const entrySize = Number.isFinite(entry.size) ? entry.size : 0;
+                    totalSize += entrySize;
+                    if (totalSize > maxExtractedBytes) {
+                        throw new Error(`Tar extracted size exceeds maximum (${maxExtractedBytes} bytes).`);
+                    }
+                } catch (err) {
+                    validationError = err;
+                }
+            },
+        });
+    });
+
+    if (validationError) {
+        throw validationError;
+    }
+
+    return { entryCount, totalSize };
+}
+
+export async function packArtifact(sourceDir, outputFile, signingSecret) {
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+
+    await tarCreate(
+        {
+            gzip: true,
+            cwd: sourceDir,
+            file: outputFile,
+            portable: true,
+            noMtime: true,
+        },
+        ['.']
+    );
+
+    const buffer = fs.readFileSync(outputFile);
+    const sha256 = computeSha256Hex(buffer);
+    const signature = signSha256Hex(sha256, signingSecret);
+
+    return {
+        file: outputFile,
+        sha256,
+        signature,
+        sizeBytes: buffer.length,
+    };
+}

package/src/lib/config.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CONFIG_FILENAME = '.challengerc.json';
+
+function getConfigPath() {
+    return path.join(os.homedir(), CONFIG_FILENAME);
+}
+
+export function loadConfig() {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch {
+        return {};
+    }
+}
+
+export function saveConfig(config) {
+    const configPath = getConfigPath();
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    return configPath;
+}
+
+export function resolveApiUrl(flagValue) {
+    return (
+        flagValue ||
+        process.env.CKS_API_BASE_URL ||
+        loadConfig().apiUrl ||
+        'http://127.0.0.1:3000'
+    ).replace(/\/$/, '');
+}
+
+export function resolveToken(flagValue) {
+    return flagValue || process.env.CKS_API_TOKEN || loadConfig().token || null;
+}
+
+export function resolveSigningSecret(flagValue) {
+    return (
+        flagValue ||
+        process.env.CHALLENGE_ARTIFACT_SIGNING_SECRET ||
+        loadConfig().signingSecret ||
+        null
+    );
+}

package/src/lib/helpers.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+
+const SLUG_PATTERN = /^[a-z0-9-]+$/;
+const PACKAGE_NAME_PATTERN = /^(?:@[-a-z0-9~][a-z0-9-._~]*\/)?[a-z0-9~][a-z0-9-._~]*$/i;
+const EXACT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+
+export function assertSlug(slug) {
+    if (!slug || !SLUG_PATTERN.test(slug)) {
+        throw new Error(`Invalid challenge slug: "${slug}". Must be lowercase alphanumeric with dashes.`);
+    }
+}
+
+export function assertPinnedAllowedDependencies(allowedDependencies) {
+    if (!Array.isArray(allowedDependencies) || allowedDependencies.length === 0) {
+        throw new Error('challenge.json allowedDependencies must be a non-empty array.');
+    }
+
+    const seen = new Map();
+    for (const rawSpec of allowedDependencies) {
+        if (typeof rawSpec !== 'string' || rawSpec.trim() === '') {
+            throw new Error('allowedDependencies entries must be non-empty strings.');
+        }
+
+        const spec = rawSpec.trim();
+        const splitIndex = spec.lastIndexOf('@');
+        if (splitIndex <= 0) {
+            throw new Error(`Dependency "${spec}" must use package@x.y.z format.`);
+        }
+
+        const name = spec.slice(0, splitIndex).trim();
+        const version = spec.slice(splitIndex + 1).trim();
+        if (!PACKAGE_NAME_PATTERN.test(name)) {
+            throw new Error(`Invalid dependency name in allowedDependencies: ${name}`);
+        }
+        if (!EXACT_VERSION_PATTERN.test(version)) {
+            throw new Error(`Dependency "${spec}" must pin an exact version (x.y.z).`);
+        }
+
+        const existing = seen.get(name);
+        if (existing && existing !== version) {
+            throw new Error(`Conflicting allowed dependency versions for ${name}.`);
+        }
+        seen.set(name, version);
+    }
+}
+
+export function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJson(filePath, payload) {
+    fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+export function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function hashBuffer(value) {
+    return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+export function findFirstExistingFile(paths) {
+    for (const filePath of paths) {
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+
+const RUNTIME_MODE_VALUES = new Set(['auto', 'manual']);
+
+export function resolveRuntimeMode(mode) {
+    const normalized = (mode || 'auto').toLowerCase();
+    if (!RUNTIME_MODE_VALUES.has(normalized)) {
+        throw new Error(
+            `Invalid runtime mode: ${mode}. Supported values: ${Array.from(RUNTIME_MODE_VALUES).join(', ')}`
+        );
+    }
+    return normalized;
+}

package/src/lib/http.js

@@ -0,0 +1,70 @@
+const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+
+function resolveHttpTimeoutMs() {
+    const parsed = Number.parseInt(process.env.CKS_HTTP_TIMEOUT_MS || '', 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return DEFAULT_HTTP_TIMEOUT_MS;
+    }
+    return parsed;
+}
+
+export async function fetchWithTimeout(url, options = {}) {
+    const timeoutMs = resolveHttpTimeoutMs();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+        return await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+    } catch (err) {
+        if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+            const method = options.method || 'GET';
+            throw new Error(`Request timed out after ${timeoutMs}ms: ${method} ${url}`);
+        }
+        throw err;
+    } finally {
+        clearTimeout(timeoutId);
+    }
+}
+
+export async function requestJson(url, { method, body, token }) {
+    const headers = {
+        'content-type': 'application/json',
+    };
+    if (token) {
+        headers.authorization = `Bearer ${token}`;
+    }
+
+    const response = await fetchWithTimeout(url, {
+        method,
+        headers,
+        body: body == null ? undefined : JSON.stringify(body),
+    });
+
+    const rawBody = await response.text();
+    let payload = {};
+    if (rawBody && rawBody.trim() !== '') {
+        try {
+            payload = JSON.parse(rawBody);
+        } catch (err) {
+            const parseError = new Error(
+                `Invalid JSON response from ${method} ${url}: ${err.message}`
+            );
+            parseError.status = response.status;
+            parseError.responseText = rawBody.slice(0, 2000);
+            throw parseError;
+        }
+    }
+
+    if (!response.ok) {
+        const message = payload && payload.error ? payload.error : `Request failed: ${method} ${url} (${response.status})`;
+        const error = new Error(message);
+        error.status = response.status;
+        error.payload = payload;
+        throw error;
+    }
+
+    return payload;
+}

package/src/lib/runtime-deps.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { hashBuffer, findFirstExistingFile, writeJson } from './helpers.js';
+
+function quoteWindowsArg(arg) {
+    const value = String(arg);
+    if (!/[ \t"]/g.test(value)) return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+
+function runCommand(command, args, { cwd }) {
+    return new Promise((resolve, reject) => {
+        const isWindows = process.platform === 'win32';
+        const spawnCommand = isWindows ? 'cmd.exe' : command;
+        const spawnArgs = isWindows
+            ? ['/d', '/s', '/c', [command, ...args].map(quoteWindowsArg).join(' ')]
+            : args;
+
+        const child = spawn(spawnCommand, spawnArgs, {
+            cwd,
+            shell: false,
+            env: { ...process.env, npm_config_loglevel: 'error' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        const stdoutChunks = [];
+        const stderrChunks = [];
+
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('error', reject);
+
+        child.on('close', (code) => {
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
+            if (code !== 0) {
+                reject(
+                    new Error(
+                        [
+                            `Command failed: ${command} ${args.join(' ')}`,
+                            stdout ? `stdout:\n${stdout}` : null,
+                            stderr ? `stderr:\n${stderr}` : null,
+                        ]
+                            .filter(Boolean)
+                            .join('\n')
+                    )
+                );
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+
+function computeRuntimeDepsCacheKey(manifestDir) {
+    const packageJsonPath = path.join(manifestDir, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        throw new Error(`Runtime manifest package.json not found: ${packageJsonPath}`);
+    }
+
+    const lockFilePath = findFirstExistingFile([
+        path.join(manifestDir, 'package-lock.json'),
+        path.join(manifestDir, 'npm-shrinkwrap.json'),
+    ]);
+
+    const keyPayload = [
+        `platform:${process.platform}`,
+        `arch:${process.arch}`,
+        `node-major:${process.versions.node.split('.')[0]}`,
+        fs.readFileSync(packageJsonPath),
+        lockFilePath ? fs.readFileSync(lockFilePath) : 'no-lockfile',
+    ];
+
+    return hashBuffer(
+        Buffer.concat(
+            keyPayload.map((item) =>
+                Buffer.isBuffer(item) ? item : Buffer.from(String(item), 'utf8')
+            )
+        )
+    );
+}
+
+async function buildRuntimeDepsFromManifest({ challengeDir, manifestDir, log }) {
+    const packageJsonPath = path.join(manifestDir, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        throw new Error(`Runtime manifest package.json not found: ${packageJsonPath}`);
+    }
+
+    const lockFilePath = findFirstExistingFile([
+        path.join(manifestDir, 'package-lock.json'),
+        path.join(manifestDir, 'npm-shrinkwrap.json'),
+    ]);
+    const cacheKey = computeRuntimeDepsCacheKey(manifestDir);
+    const cacheRoot = path.join(challengeDir, '.cache', 'runtime-deps');
+    const cacheDir = path.join(cacheRoot, cacheKey);
+    const cachedNodeModules = path.join(cacheDir, 'node_modules');
+
+    if (fs.existsSync(cachedNodeModules)) {
+        log(`Using cached runtime deps (key: ${cacheKey.slice(0, 12)}…)`);
+        return cacheDir;
+    }
+
+    const tempBuildRoot = await fs.promises.mkdtemp(
+        path.join(os.tmpdir(), 'challenge-cli-runtime-deps-')
+    );
+
+    try {
+        const tempManifestDir = path.join(tempBuildRoot, 'manifest');
+        await fs.promises.mkdir(tempManifestDir, { recursive: true });
+        await fs.promises.copyFile(packageJsonPath, path.join(tempManifestDir, 'package.json'));
+        if (lockFilePath) {
+            await fs.promises.copyFile(
+                lockFilePath,
+                path.join(tempManifestDir, path.basename(lockFilePath))
+            );
+        }
+
+        const installArgs = lockFilePath
+            ? ['ci', '--omit=dev', '--ignore-scripts']
+            : ['install', '--omit=dev', '--ignore-scripts'];
+
+        log(`Building runtime deps (${lockFilePath ? 'npm ci' : 'npm install'})…`);
+        await runCommand('npm', installArgs, { cwd: tempManifestDir });
+
+        const builtNodeModules = path.join(tempManifestDir, 'node_modules');
+        if (!fs.existsSync(builtNodeModules)) {
+            await fs.promises.mkdir(builtNodeModules, { recursive: true });
+        }
+
+        await fs.promises.mkdir(cacheDir, { recursive: true });
+        fs.cpSync(builtNodeModules, cachedNodeModules, { recursive: true });
+        writeJson(path.join(cacheDir, 'build-metadata.json'), {
+            cacheKey,
+            builtAt: new Date().toISOString(),
+            packageJsonSha256: hashBuffer(fs.readFileSync(packageJsonPath)),
+            lockFile: lockFilePath ? path.basename(lockFilePath) : null,
+            lockFileSha256: lockFilePath ? hashBuffer(fs.readFileSync(lockFilePath)) : null,
+            platform: process.platform,
+            arch: process.arch,
+            nodeVersion: process.versions.node,
+        });
+
+        return cacheDir;
+    } finally {
+        await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+    }
+}
+
+export async function resolveRuntimeDepsSourceDir({ challengeDir, runtimeMode, log = () => { } }) {
+    const manualRuntimeDepsDir = path.join(challengeDir, 'artifacts', 'runtime_deps');
+    const runtimeManifestDir = path.join(challengeDir, 'artifacts', 'runtime_manifest');
+    const runtimeManifestPackageJson = path.join(runtimeManifestDir, 'package.json');
+
+    if (runtimeMode === 'manual') {
+        if (!fs.existsSync(manualRuntimeDepsDir)) {
+            throw new Error(`Missing artifact source directory: ${manualRuntimeDepsDir}`);
+        }
+        return manualRuntimeDepsDir;
+    }
+
+    if (fs.existsSync(runtimeManifestPackageJson)) {
+        return buildRuntimeDepsFromManifest({ challengeDir, manifestDir: runtimeManifestDir, log });
+    }
+
+    if (!fs.existsSync(manualRuntimeDepsDir)) {
+        throw new Error(
+            [
+                `Missing runtime deps sources for challenge at ${challengeDir}.`,
+                'Expected either:',
+                `  - ${runtimeManifestPackageJson} (auto mode)`,
+                `  - ${manualRuntimeDepsDir} (manual mode)`,
+            ].join('\n')
+        );
+    }
+
+    return manualRuntimeDepsDir;
+}