evolved-monkey 0.1.0

package/src/lib/backend-client.ts

@@ -0,0 +1,129 @@
+import { CliError } from "./cli-error.js";
+import type {
+  ArtifactUploadResponse,
+  ArtifactUploadTarget,
+  BackendClientContract,
+  ChallengeDraftPayload,
+  ChallengeDraftResponse,
+} from "../types.js";
+
+type ApiPayload = {
+  data?: {
+    challenge?: ChallengeDraftResponse;
+  } & Partial<ArtifactUploadResponse>;
+  error?: {
+    code?: string;
+    message?: string;
+  };
+};
+
+async function parseJsonSafely(response: Response): Promise<ApiPayload | null> {
+  const text = await response.text();
+
+  if (!text) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text) as ApiPayload;
+  } catch {
+    return null;
+  }
+}
+
+async function requestJson(url: string, options: RequestInit = {}): Promise<ApiPayload> {
+  const response = await fetch(url, options);
+  const payload = await parseJsonSafely(response);
+
+  if (!response.ok) {
+    const apiMessage = payload?.error?.message;
+    throw new CliError(apiMessage ?? `Backend request failed (${response.status})`, {
+      code: payload?.error?.code ?? "BACKEND_REQUEST_FAILED",
+      details: payload,
+    });
+  }
+
+  return payload ?? {};
+}
+
+export class BackendClient implements BackendClientContract {
+  private readonly baseUrl: string;
+
+  public constructor(baseUrl: string) {
+    this.baseUrl = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  }
+
+  public async createChallengeDraft(input: ChallengeDraftPayload): Promise<ChallengeDraftResponse> {
+    const payload = await requestJson(`${this.baseUrl}/v1/creator/challenges/init`, {
+      body: JSON.stringify(input),
+      headers: {
+        "content-type": "application/json",
+      },
+      method: "POST",
+    });
+
+    const challenge = payload?.data?.challenge;
+
+    if (!challenge) {
+      throw new CliError("Backend did not return created challenge data.", {
+        code: "INVALID_BACKEND_RESPONSE",
+      });
+    }
+
+    return challenge;
+  }
+
+  public async requestStarterUpload(slug: string): Promise<ArtifactUploadResponse> {
+    const payload = await requestJson(
+      `${this.baseUrl}/v1/creator/challenges/${encodeURIComponent(slug)}/artifacts/starter/upload-url`,
+      {
+        method: "POST",
+      },
+    );
+
+    if (!payload.data || !("upload" in payload.data)) {
+      throw new CliError("Backend did not return starter upload target.", {
+        code: "INVALID_BACKEND_RESPONSE",
+      });
+    }
+
+    return payload.data as ArtifactUploadResponse;
+  }
+
+  public async requestTestsUpload(slug: string): Promise<ArtifactUploadResponse> {
+    const payload = await requestJson(
+      `${this.baseUrl}/v1/creator/challenges/${encodeURIComponent(slug)}/artifacts/tests/upload-url`,
+      {
+        method: "POST",
+      },
+    );
+
+    if (!payload.data || !("upload" in payload.data)) {
+      throw new CliError("Backend did not return tests upload target.", {
+        code: "INVALID_BACKEND_RESPONSE",
+      });
+    }
+
+    return payload.data as ArtifactUploadResponse;
+  }
+
+  public async uploadArtifact(upload: ArtifactUploadTarget, fileBuffer: Buffer): Promise<void> {
+    const headers = new Headers(upload.headers ?? {});
+
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/gzip");
+    }
+
+    const response = await fetch(upload.url, {
+      body: new Uint8Array(fileBuffer),
+      headers,
+      method: upload.method ?? "PUT",
+    });
+
+    if (!response.ok) {
+      throw new CliError(`Artifact upload failed (${response.status})`, {
+        code: "ARTIFACT_UPLOAD_FAILED",
+      });
+    }
+  }
+}

package/src/lib/cli-error.ts

@@ -0,0 +1,19 @@
+export type CliErrorOptions = {
+  code?: string;
+  details?: unknown;
+  exitCode?: number;
+};
+
+export class CliError extends Error {
+  public readonly code: string;
+  public readonly details?: unknown;
+  public readonly exitCode: number;
+
+  public constructor(message: string, options: CliErrorOptions = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = options.code ?? "CLI_ERROR";
+    this.details = options.details;
+    this.exitCode = options.exitCode ?? 1;
+  }
+}

package/src/lib/fs-utils.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJsonFile<T>(filePath: string): Promise<T> {
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(content) as T;
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  const content = JSON.stringify(value, null, 2);
+  await fs.writeFile(filePath, `${content}\n`, "utf8");
+}
+
+export async function walkFilesRecursively(rootDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function visit(currentDir: string): Promise<void> {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolutePath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+
+      files.push(absolutePath);
+    }
+  }
+
+  await visit(rootDir);
+  return files;
+}

package/src/lib/tarball.ts

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+
+import { CliError } from "./cli-error.js";
+
+export type CreateTarballInput = {
+  excludePatterns?: readonly string[];
+  outputFile: string;
+  sourceDir: string;
+};
+
+export function createTarGzFromDirectory({
+  outputFile,
+  sourceDir,
+  excludePatterns = [],
+}: CreateTarballInput): void {
+  const args = ["-czf", outputFile];
+
+  for (const pattern of excludePatterns) {
+    args.push("--exclude", pattern);
+  }
+
+  args.push("-C", sourceDir, ".");
+
+  const result = spawnSync("tar", args, { encoding: "utf8" });
+
+  if (result.error) {
+    throw new CliError(
+      "Unable to create tar.gz archive. Ensure `tar` is installed and available in PATH.",
+      {
+        code: "TAR_COMMAND_MISSING",
+        details: result.error.message,
+      },
+    );
+  }
+
+  if (result.status !== 0) {
+    throw new CliError("Failed to create tar.gz archive.", {
+      code: "TAR_ARCHIVE_FAILED",
+      details: result.stderr || result.stdout,
+    });
+  }
+}

package/src/lib/workspace.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  CHALLENGE_CONFIG_FILE,
+  CONSTRAINTS_PLACEHOLDER,
+  DESCRIPTION_PLACEHOLDER,
+} from "../constants.js";
+import { CliError } from "./cli-error.js";
+import { pathExists, readJsonFile, walkFilesRecursively } from "./fs-utils.js";
+
+const challengeSlugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export type ChallengeWorkspaceConfig = {
+  backendBaseUrl: string;
+  challengeId: string | null;
+  constraintsMd: string;
+  createdAt: string;
+  descriptionMd: string;
+  slug: string;
+  title: string;
+  type: "EXPRESS_NODE";
+  version: number;
+};
+
+export type WorkspaceValidationResult = {
+  errors: string[];
+  ok: boolean;
+  warnings: string[];
+};
+
+export function normalizeSlug(slug: unknown): string {
+  return String(slug ?? "")
+    .trim()
+    .toLowerCase();
+}
+
+export function ensureValidSlug(slug: unknown): string {
+  const value = normalizeSlug(slug);
+
+  if (!challengeSlugRegex.test(value)) {
+    throw new CliError(
+      "Slug must be lowercase kebab-case (letters, numbers, and hyphens only).",
+      {
+        code: "INVALID_SLUG",
+      },
+    );
+  }
+
+  return value;
+}
+
+export async function loadChallengeConfig(workspaceDir: string): Promise<ChallengeWorkspaceConfig> {
+  const configPath = path.join(workspaceDir, CHALLENGE_CONFIG_FILE);
+
+  if (!(await pathExists(configPath))) {
+    throw new CliError(`Missing ${CHALLENGE_CONFIG_FILE} in ${workspaceDir}`, {
+      code: "MISSING_CONFIG_FILE",
+    });
+  }
+
+  return readJsonFile<ChallengeWorkspaceConfig>(configPath);
+}
+
+export async function validateWorkspace(workspaceDir: string): Promise<WorkspaceValidationResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const configPath = path.join(workspaceDir, CHALLENGE_CONFIG_FILE);
+
+  if (!(await pathExists(configPath))) {
+    errors.push(`Missing ${CHALLENGE_CONFIG_FILE}.`);
+    return { errors, ok: false, warnings };
+  }
+
+  const config = await readJsonFile<ChallengeWorkspaceConfig>(configPath);
+  const slug = normalizeSlug(config.slug);
+
+  if (!challengeSlugRegex.test(slug)) {
+    errors.push("Config slug is invalid. Use lowercase kebab-case.");
+  }
+
+  if (!config.title || String(config.title).trim().length < 3) {
+    errors.push("Config title must be at least 3 characters.");
+  }
+
+  if (!config.descriptionMd || String(config.descriptionMd).trim().length < 20) {
+    errors.push("Config descriptionMd must be at least 20 characters.");
+  }
+
+  if (String(config.descriptionMd).includes(DESCRIPTION_PLACEHOLDER)) {
+    errors.push("Replace description placeholder in challenge.config.json.");
+  }
+
+  if (!config.constraintsMd || String(config.constraintsMd).trim().length < 20) {
+    errors.push("Config constraintsMd must be at least 20 characters.");
+  }
+
+  if (String(config.constraintsMd).includes(CONSTRAINTS_PLACEHOLDER)) {
+    errors.push("Replace constraints placeholder in challenge.config.json.");
+  }
+
+  if (config.type !== "EXPRESS_NODE") {
+    errors.push("Only EXPRESS_NODE challenges are supported in V0.");
+  }
+
+  const starterDir = path.join(workspaceDir, "starter");
+  const testsDir = path.join(workspaceDir, "tests");
+
+  if (!(await pathExists(path.join(starterDir, "package.json")))) {
+    errors.push("starter/package.json is required.");
+  }
+
+  if (!(await pathExists(path.join(testsDir, "package.json")))) {
+    errors.push("tests/package.json is required.");
+  }
+
+  const disallowedPaths = [
+    path.join(starterDir, "node_modules"),
+    path.join(testsDir, "node_modules"),
+    path.join(starterDir, ".env"),
+    path.join(testsDir, ".env"),
+  ];
+
+  for (const targetPath of disallowedPaths) {
+    if (await pathExists(targetPath)) {
+      errors.push(`Disallowed path present: ${path.relative(workspaceDir, targetPath)}`);
+    }
+  }
+
+  if (await pathExists(starterDir)) {
+    const starterFiles = await walkFilesRecursively(starterDir);
+    const hiddenTestsInStarter = starterFiles.filter((filePath) =>
+      path.basename(filePath).match(/\.test\.[jt]sx?$/),
+    );
+
+    if (hiddenTestsInStarter.length > 0) {
+      errors.push("Starter must not include hidden test files.");
+    }
+  }
+
+  if (await pathExists(testsDir)) {
+    const testFiles = await walkFilesRecursively(testsDir);
+    const matchingTestFiles = testFiles.filter((filePath) =>
+      path.basename(filePath).match(/\.test\.[jt]sx?$/),
+    );
+
+    if (matchingTestFiles.length === 0) {
+      errors.push("Hidden tests package must include at least one *.test.js or *.test.ts file.");
+    }
+
+    const externalUrlRegex = /https?:\/\/(?!localhost|127\.0\.0\.1)/i;
+
+    for (const filePath of matchingTestFiles) {
+      const content = await fs.readFile(filePath, "utf8");
+      if (externalUrlRegex.test(content)) {
+        warnings.push(
+          `Potential external network usage found in tests file: ${path.relative(workspaceDir, filePath)}`,
+        );
+      }
+    }
+  }
+
+  return {
+    errors,
+    ok: errors.length === 0,
+    warnings,
+  };
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+export type FlagValue = string | boolean;
+export type CliFlags = Record<string, FlagValue | undefined>;
+
+export type ParsedArgs = {
+  flags: CliFlags;
+  positionals: string[];
+};
+
+export type Logger = (...args: string[]) => void;
+
+export type ChallengeDraftPayload = {
+  constraintsMd: string;
+  descriptionMd: string;
+  slug: string;
+  title: string;
+  type: "EXPRESS_NODE";
+};
+
+export type ChallengeDraftResponse = {
+  id: string;
+  slug: string;
+  title: string;
+  type: "EXPRESS_NODE";
+};
+
+export type ArtifactUploadTarget = {
+  expiresInSeconds: number;
+  headers: Record<string, string>;
+  key: string;
+  method: "PUT";
+  url: string;
+};
+
+export type ArtifactUploadResponse = {
+  challengeId: string;
+  challengeSlug: string;
+  upload: ArtifactUploadTarget;
+};
+
+export interface BackendClientContract {
+  createChallengeDraft(input: ChallengeDraftPayload): Promise<ChallengeDraftResponse>;
+  requestStarterUpload(slug: string): Promise<ArtifactUploadResponse>;
+  requestTestsUpload(slug: string): Promise<ArtifactUploadResponse>;
+  uploadArtifact(upload: ArtifactUploadTarget, fileBuffer: Buffer): Promise<void>;
+}

package/tests/fixtures/invalid-workspace/challenge.config.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "challengeId": "challenge-invalid",
+  "slug": "invalid_workspace",
+  "title": "No",
+  "descriptionMd": "REPLACE_WITH_CHALLENGE_DESCRIPTION",
+  "constraintsMd": "REPLACE_WITH_CHALLENGE_CONSTRAINTS",
+  "type": "EXPRESS_NODE",
+  "backendBaseUrl": "http://localhost:3001",
+  "createdAt": "2026-02-15T00:00:00.000Z"
+}

package/tests/fixtures/invalid-workspace/starter/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "starter-invalid",
+  "private": true,
+  "type": "module"
+}

package/tests/fixtures/invalid-workspace/starter/src/index.js

@@ -0,0 +1,3 @@
+export function createApp() {
+  return "invalid";
+}

package/tests/fixtures/valid-workspace/challenge.config.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "challengeId": "challenge-valid",
+  "slug": "valid-workspace-challenge",
+  "title": "Valid Workspace Challenge",
+  "descriptionMd": "Build an Express middleware that validates a custom header and forwards valid requests.",
+  "constraintsMd": "Use only express and built-in Node APIs. Do not use external services. Keep implementation deterministic.",
+  "type": "EXPRESS_NODE",
+  "backendBaseUrl": "http://localhost:3001",
+  "createdAt": "2026-02-15T00:00:00.000Z"
+}

package/tests/fixtures/valid-workspace/starter/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "starter-valid",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  }
+}

package/tests/fixtures/valid-workspace/starter/src/index.js

@@ -0,0 +1,3 @@
+export function createApp() {
+  return "ok";
+}

package/tests/fixtures/valid-workspace/tests/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "tests-valid",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test \"spec/**/*.test.js\""
+  }
+}

package/tests/fixtures/valid-workspace/tests/spec/basic.test.js

@@ -0,0 +1,6 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+test("hidden tests placeholder", () => {
+  assert.equal(1, 1);
+});

package/tests/helpers/test-utils.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export async function createTempDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+export async function copyDir(sourceDir: string, destinationDir: string): Promise<void> {
+  await fs.mkdir(destinationDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(sourcePath, destinationPath);
+      continue;
+    }
+
+    await fs.copyFile(sourcePath, destinationPath);
+  }
+}
+
+export function resolveFixturePath(relativePath: string): string {
+  return path.resolve(process.cwd(), "tests", "fixtures", relativePath);
+}
+
+export function resolveSnapshotPath(relativePath: string): string {
+  return path.resolve(process.cwd(), "tests", "snapshots", relativePath);
+}