evolved-monkey 0.1.0

package/dist/tests/unit/cli-commands.spec.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runChallengeInit } from "../../src/commands/challenge-init.js";
+import { runChallengeValidate } from "../../src/commands/challenge-validate.js";
+import { readJsonFile } from "../../src/lib/fs-utils.js";
+import { copyDir, createTempDir, resolveFixturePath, resolveSnapshotPath, } from "../helpers/test-utils.js";
+class FakeBackendClient {
+    async createChallengeDraft(input) {
+        return {
+            id: "challenge-snapshot-id",
+            slug: input.slug,
+            title: input.title,
+            type: "EXPRESS_NODE",
+        };
+    }
+    async requestStarterUpload(_slug) {
+        throw new Error("Not used in this unit test.");
+    }
+    async requestTestsUpload(_slug) {
+        throw new Error("Not used in this unit test.");
+    }
+    async uploadArtifact(_upload, _fileBuffer) {
+        throw new Error("Not used in this unit test.");
+    }
+}
+export async function runCliCommandsUnitTests() {
+    const tempRoot = await createTempDir("em-cli-unit-");
+    try {
+        const initResult = await runChallengeInit({
+            backendClient: new FakeBackendClient(),
+            cwd: tempRoot,
+            flags: {
+                constraints: "Use only express and built-in APIs. Keep runtime deterministic and avoid external services.",
+                description: "Build a middleware that validates incoming headers and returns clear JSON error responses.",
+                slug: "snapshot-challenge",
+                title: "Snapshot Challenge",
+            },
+            log: () => { },
+        });
+        const normalizedInitResult = {
+            ...initResult,
+            workspaceDir: "<workspace>",
+        };
+        const snapshotPath = resolveSnapshotPath("init-result.json");
+        const expectedSnapshot = JSON.parse(await fs.readFile(snapshotPath, "utf8"));
+        assert.deepEqual(normalizedInitResult, expectedSnapshot);
+        const configPath = path.join(initResult.workspaceDir, "challenge.config.json");
+        const config = await readJsonFile(configPath);
+        assert.equal(config.slug, "snapshot-challenge");
+        assert.equal(config.type, "EXPRESS_NODE");
+        const validResult = await runChallengeValidate({
+            cwd: initResult.workspaceDir,
+            flags: {},
+            log: () => { },
+        });
+        assert.equal(validResult.ok, true);
+        const invalidFixtureSource = resolveFixturePath("invalid-workspace");
+        const invalidFixtureTarget = path.join(tempRoot, "invalid-workspace");
+        await copyDir(invalidFixtureSource, invalidFixtureTarget);
+        const invalidResult = await runChallengeValidate({
+            cwd: invalidFixtureTarget,
+            flags: {},
+            log: () => { },
+        });
+        assert.equal(invalidResult.ok, false);
+        assert.equal(invalidResult.errors.length > 0, true);
+    }
+    finally {
+        await fs.rm(tempRoot, { force: true, recursive: true });
+    }
+}
+//# sourceMappingURL=cli-commands.spec.js.map

package/dist/tests/unit/cli-commands.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-commands.spec.js","sourceRoot":"","sources":["../../../tests/unit/cli-commands.spec.ts"],"names":[],"mappings":"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"}

package/docs/01.md

@@ -0,0 +1,39 @@
+1.
+  - challenge init
+      - Creates draft challenge in backend
+      - Scaffolds local creator workspace with:
+          - challenge.config.json
+          - starter/
+          - tests/
+          - README.md
+  - challenge validate
+      - Enforces creator rules from docs/challenge-creator-guidelines.md:
+          - valid slug/title/description/constraints
+          - required files present
+          - disallowed files (node_modules, .env) not present
+          - hidden tests exist
+          - starter doesn’t contain hidden test files
+  - challenge submit
+      - Validates workspace first
+      - Requests signed upload URLs from backend
+      - Packs starter/ and tests/ as tar.gz
+      - Uploads both artifacts to R2 via signed URLs
+
+  Files added/updated:
+
+  - cli/package.json
+  - cli/src/index.js
+  - cli/src/cli.js
+  - cli/src/constants.js
+  - cli/src/commands/challenge-init.js
+  - cli/src/commands/challenge-validate.js
+  - cli/src/commands/challenge-submit.js
+  - cli/src/lib/* helpers (args, backend-client, workspace, tarball, etc.)
+  - cli/tests/* (fixtures, snapshots, unit + integration tests)
+  - cli/README.md
+  - docs/v0-tasklist.md (Task 4 marked complete)
+
+  Tests:
+
+  - Ran cd cli && npm test
+  - Result: all tests passed (unit + backend test server integration).

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "evolved-monkey",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "em-challenge": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "node dist/tests/run-tests.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,86 @@
+import { DEFAULT_BACKEND_BASE_URL } from "./constants.js";
+import { runChallengeInit } from "./commands/challenge-init.js";
+import { runChallengeSubmit } from "./commands/challenge-submit.js";
+import { runChallengeValidate } from "./commands/challenge-validate.js";
+import { BackendClient } from "./lib/backend-client.js";
+import { parseArgs } from "./lib/args.js";
+import { CliError } from "./lib/cli-error.js";
+import type { PackageDirectoryInput } from "./commands/challenge-submit.js";
+import type { BackendClientContract, CliFlags, Logger } from "./types.js";
+
+type CliContext = {
+  backendClient?: BackendClientContract;
+  cwd?: string;
+  log?: Logger;
+  packageDirectory?: (input: PackageDirectoryInput) => Promise<Buffer>;
+};
+
+function resolveBackendBaseUrl(flags: CliFlags, command: string): string {
+  if (flags.backend && flags.backend !== true) {
+    return String(flags.backend);
+  }
+
+  if (command === "challenge" && (flags.dir || flags.dir === "")) {
+    return process.env.BACKEND_BASE_URL ?? DEFAULT_BACKEND_BASE_URL;
+  }
+
+  return process.env.BACKEND_BASE_URL ?? DEFAULT_BACKEND_BASE_URL;
+}
+
+function usageText(): string {
+  return [
+    "Usage:",
+    "  em-challenge challenge init --slug <slug> --title <title> [--description <text>] [--constraints <text>] [--backend <url>] [--dir <path>]",
+    "  em-challenge challenge validate [--dir <path>]",
+    "  em-challenge challenge submit [--backend <url>] [--dir <path>]",
+  ].join("\n");
+}
+
+export async function runCli(rawArgv: string[], context: CliContext = {}) {
+  const argv = rawArgv.slice();
+  const { flags, positionals } = parseArgs(argv);
+  const log = context.log ?? console.log;
+  const cwd = context.cwd ?? process.cwd();
+
+  const [domain, command] = positionals;
+
+  if (!domain || !command) {
+    throw new CliError(usageText(), { code: "USAGE_ERROR" });
+  }
+
+  if (domain !== "challenge") {
+    throw new CliError(`Unsupported domain: ${domain}\n\n${usageText()}`, { code: "USAGE_ERROR" });
+  }
+
+  const backendBaseUrl = resolveBackendBaseUrl(flags, domain);
+  const backendClient =
+    context.backendClient ?? new BackendClient(backendBaseUrl);
+
+  if (command === "init") {
+    return runChallengeInit({ backendClient, cwd, flags, log });
+  }
+
+  if (command === "validate") {
+    const result = await runChallengeValidate({ cwd, flags, log });
+    if (!result.ok) {
+      throw new CliError("Validation failed.", {
+        code: "VALIDATION_FAILED",
+        details: result.errors,
+      });
+    }
+
+    return result;
+  }
+
+  if (command === "submit") {
+    return runChallengeSubmit({
+      backendClient,
+      cwd,
+      flags,
+      log,
+      packageDirectory: context.packageDirectory,
+    });
+  }
+
+  throw new CliError(`Unsupported command: ${command}\n\n${usageText()}`, { code: "USAGE_ERROR" });
+}

package/src/commands/challenge-init.ts

@@ -0,0 +1,162 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  CHALLENGE_CONFIG_FILE,
+  CONSTRAINTS_PLACEHOLDER,
+  DEFAULT_BACKEND_BASE_URL,
+  DESCRIPTION_PLACEHOLDER,
+} from "../constants.js";
+import { CliError } from "../lib/cli-error.js";
+import { ensureDir, pathExists, writeJsonFile } from "../lib/fs-utils.js";
+import { ensureValidSlug } from "../lib/workspace.js";
+import type {
+  BackendClientContract,
+  ChallengeDraftPayload,
+  CliFlags,
+  Logger,
+} from "../types.js";
+
+type ChallengeInitInput = {
+  backendClient: BackendClientContract;
+  cwd?: string;
+  flags: CliFlags;
+  log?: Logger;
+};
+
+type ChallengeInitResult = {
+  challengeId: string | null;
+  slug: string;
+  workspaceDir: string;
+};
+
+function resolveOption(flags: CliFlags, key: string, fallback: string): string {
+  const value = flags[key];
+  if (value === undefined || value === true || value === "") {
+    return fallback;
+  }
+
+  return String(value);
+}
+
+async function createStarterTemplate(workspaceDir: string): Promise<void> {
+  const starterDir = path.join(workspaceDir, "starter");
+  await ensureDir(path.join(starterDir, "src"));
+
+  const starterPackage = {
+    name: "challenge-starter",
+    private: true,
+    scripts: {
+      start: "node src/index.js",
+      test: "node --test",
+    },
+    type: "module",
+    version: "1.0.0",
+  };
+
+  await writeJsonFile(path.join(starterDir, "package.json"), starterPackage);
+  await fs.writeFile(
+    path.join(starterDir, "src", "index.js"),
+    `export function createApp() {\n  return "replace-with-solution";\n}\n`,
+    "utf8",
+  );
+  await fs.writeFile(path.join(starterDir, ".env.example"), "PORT=3000\n", "utf8");
+}
+
+async function createHiddenTestsTemplate(workspaceDir: string): Promise<void> {
+  const testsDir = path.join(workspaceDir, "tests");
+  await ensureDir(path.join(testsDir, "spec"));
+
+  const testsPackage = {
+    name: "challenge-hidden-tests",
+    private: true,
+    scripts: {
+      test: "node --test \"spec/**/*.test.js\"",
+    },
+    type: "module",
+    version: "1.0.0",
+  };
+
+  await writeJsonFile(path.join(testsDir, "package.json"), testsPackage);
+  await fs.writeFile(
+    path.join(testsDir, "spec", "placeholder.test.js"),
+    `import test from "node:test";\nimport assert from "node:assert/strict";\n\ntest("replace with real hidden tests", () => {\n  assert.equal(true, true);\n});\n`,
+    "utf8",
+  );
+}
+
+export async function runChallengeInit({
+  backendClient,
+  cwd = process.cwd(),
+  flags,
+  log = console.log,
+}: ChallengeInitInput): Promise<ChallengeInitResult> {
+  const slug = ensureValidSlug(flags.slug);
+  const title = resolveOption(flags, "title", "");
+
+  if (!title || title.length < 3) {
+    throw new CliError("`--title` is required and must be at least 3 characters.", {
+      code: "INVALID_TITLE",
+    });
+  }
+
+  const descriptionMd = resolveOption(flags, "description", DESCRIPTION_PLACEHOLDER);
+  const constraintsMd = resolveOption(flags, "constraints", CONSTRAINTS_PLACEHOLDER);
+  const backendBaseUrl = resolveOption(
+    flags,
+    "backend",
+    process.env.BACKEND_BASE_URL ?? DEFAULT_BACKEND_BASE_URL,
+  );
+  const workspaceDir = path.resolve(cwd, resolveOption(flags, "dir", slug));
+
+  if (await pathExists(workspaceDir)) {
+    throw new CliError(`Target directory already exists: ${workspaceDir}`, {
+      code: "DIRECTORY_EXISTS",
+    });
+  }
+
+  const payload: ChallengeDraftPayload = {
+    constraintsMd,
+    descriptionMd,
+    slug,
+    title,
+    type: "EXPRESS_NODE",
+  };
+
+  const createdChallenge = await backendClient.createChallengeDraft(payload);
+
+  await ensureDir(workspaceDir);
+  await createStarterTemplate(workspaceDir);
+  await createHiddenTestsTemplate(workspaceDir);
+
+  const config = {
+    backendBaseUrl,
+    challengeId: createdChallenge?.id ?? null,
+    constraintsMd,
+    createdAt: new Date().toISOString(),
+    descriptionMd,
+    slug,
+    title,
+    type: "EXPRESS_NODE",
+    version: 1,
+  };
+
+  await writeJsonFile(path.join(workspaceDir, CHALLENGE_CONFIG_FILE), config);
+  await fs.writeFile(
+    path.join(workspaceDir, "README.md"),
+    `# ${title}\n\n## Description\n${descriptionMd}\n\n## Constraints\n${constraintsMd}\n`,
+    "utf8",
+  );
+
+  log(`Challenge workspace created: ${workspaceDir}`);
+  log(`Next steps:`);
+  log(`1) cd ${workspaceDir}`);
+  log(`2) em-challenge challenge validate`);
+  log(`3) em-challenge challenge submit`);
+
+  return {
+    challengeId: createdChallenge?.id ?? null,
+    slug,
+    workspaceDir,
+  };
+}

package/src/commands/challenge-submit.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CHALLENGE_CONFIG_FILE, EXCLUDED_ARTIFACT_PATTERNS } from "../constants.js";
+import { CliError } from "../lib/cli-error.js";
+import { readJsonFile } from "../lib/fs-utils.js";
+import { createTarGzFromDirectory } from "../lib/tarball.js";
+import { runChallengeValidate } from "./challenge-validate.js";
+import type { ChallengeWorkspaceConfig } from "../lib/workspace.js";
+import type { BackendClientContract, CliFlags, Logger } from "../types.js";
+
+export type PackageDirectoryInput = {
+  archiveNamePrefix: string;
+  sourceDir: string;
+};
+
+type ChallengeSubmitInput = {
+  backendClient: BackendClientContract;
+  cwd?: string;
+  flags: CliFlags;
+  log?: Logger;
+  packageDirectory?: (input: PackageDirectoryInput) => Promise<Buffer>;
+};
+
+export type ChallengeSubmitResult = {
+  slug: string;
+  starterArtifactKey: string;
+  testsArtifactKey: string;
+};
+
+export async function packageDirectoryToTarGz({
+  archiveNamePrefix,
+  sourceDir,
+}: PackageDirectoryInput): Promise<Buffer> {
+  const archivePath = path.join(
+    os.tmpdir(),
+    `${archiveNamePrefix}-${Date.now()}-${Math.random().toString(36).slice(2)}.tar.gz`,
+  );
+
+  createTarGzFromDirectory({
+    excludePatterns: EXCLUDED_ARTIFACT_PATTERNS,
+    outputFile: archivePath,
+    sourceDir,
+  });
+
+  const fileBuffer = await fs.readFile(archivePath);
+  await fs.rm(archivePath, { force: true });
+  return fileBuffer;
+}
+
+export async function runChallengeSubmit({
+  backendClient,
+  cwd = process.cwd(),
+  flags,
+  log = console.log,
+  packageDirectory = packageDirectoryToTarGz,
+}: ChallengeSubmitInput): Promise<ChallengeSubmitResult> {
+  const validation = await runChallengeValidate({ cwd, flags, log: () => {} });
+
+  if (!validation.ok) {
+    throw new CliError(
+      `Cannot submit challenge. Validation failed. Fix ${CHALLENGE_CONFIG_FILE} and workspace files first.`,
+      {
+        code: "VALIDATION_FAILED",
+        details: validation.errors,
+      },
+    );
+  }
+
+  const workspaceDir = validation.workspaceDir;
+  const config = await readJsonFile<ChallengeWorkspaceConfig>(
+    path.join(workspaceDir, CHALLENGE_CONFIG_FILE),
+  );
+  const slug = config.slug;
+
+  const starterUploadData = await backendClient.requestStarterUpload(slug);
+  const testsUploadData = await backendClient.requestTestsUpload(slug);
+
+  const starterBuffer = await packageDirectory({
+    archiveNamePrefix: `${slug}-starter`,
+    sourceDir: path.join(workspaceDir, "starter"),
+  });
+  const testsBuffer = await packageDirectory({
+    archiveNamePrefix: `${slug}-tests`,
+    sourceDir: path.join(workspaceDir, "tests"),
+  });
+
+  await backendClient.uploadArtifact(starterUploadData.upload, starterBuffer);
+  await backendClient.uploadArtifact(testsUploadData.upload, testsBuffer);
+
+  log(`Submitted challenge artifacts for ${slug}.`);
+  log(`Starter artifact key: ${starterUploadData.upload.key}`);
+  log(`Tests artifact key: ${testsUploadData.upload.key}`);
+
+  return {
+    slug,
+    starterArtifactKey: starterUploadData.upload.key,
+    testsArtifactKey: testsUploadData.upload.key,
+  };
+}

package/src/commands/challenge-validate.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+
+import { validateWorkspace } from "../lib/workspace.js";
+import type { CliFlags, Logger } from "../types.js";
+import type { WorkspaceValidationResult } from "../lib/workspace.js";
+
+type ChallengeValidateInput = {
+  cwd?: string;
+  flags: CliFlags;
+  log?: Logger;
+};
+
+export type ChallengeValidateResult = WorkspaceValidationResult & {
+  workspaceDir: string;
+};
+
+export async function runChallengeValidate({
+  cwd = process.cwd(),
+  flags,
+  log = console.log,
+}: ChallengeValidateInput): Promise<ChallengeValidateResult> {
+  const workspaceDir = path.resolve(cwd, String(flags.dir || "."));
+  const result = await validateWorkspace(workspaceDir);
+
+  if (!result.ok) {
+    log(`Validation failed for workspace: ${workspaceDir}`);
+    for (const error of result.errors) {
+      log(`- ERROR: ${error}`);
+    }
+    for (const warning of result.warnings) {
+      log(`- WARNING: ${warning}`);
+    }
+    return {
+      ...result,
+      workspaceDir,
+    };
+  }
+
+  log(`Validation passed for workspace: ${workspaceDir}`);
+  for (const warning of result.warnings) {
+    log(`- WARNING: ${warning}`);
+  }
+
+  return {
+    ...result,
+    workspaceDir,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,13 @@
+export const DEFAULT_BACKEND_BASE_URL = "http://localhost:3001";
+export const CHALLENGE_CONFIG_FILE = "challenge.config.json";
+
+export const DESCRIPTION_PLACEHOLDER = "REPLACE_WITH_CHALLENGE_DESCRIPTION";
+export const CONSTRAINTS_PLACEHOLDER = "REPLACE_WITH_CHALLENGE_CONSTRAINTS";
+
+export const EXCLUDED_ARTIFACT_PATTERNS = [
+  "node_modules",
+  ".git",
+  ".DS_Store",
+  "*.log",
+  ".env",
+] as const;

package/src/index.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { CliError } from "./lib/cli-error.js";
+import { runCli } from "./cli.js";
+
+async function main() {
+  try {
+    await runCli(process.argv.slice(2));
+  } catch (error: unknown) {
+    if (error instanceof CliError) {
+      console.error(error.message);
+      process.exit(error.exitCode);
+      return;
+    }
+
+    console.error("Unexpected CLI error.");
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+void main();

package/src/lib/args.ts

@@ -0,0 +1,31 @@
+import type { ParsedArgs } from "../types.js";
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const flags: ParsedArgs["flags"] = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[index + 1];
+
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+
+    flags[key] = next;
+    index += 1;
+  }
+
+  return { flags, positionals };
+}