opencode-leetcode-realworld 0.4.0 → 0.5.0

package/README.md

@@ -172,13 +172,33 @@ they tend to produce:
 | **Mini project** | A small multi-file app (~3-6 files) with the algorithm behind a single `TODO` (TypeScript, Python, Rust). |
 | **Fuller project** | A multi-file app with more realistic layers (~6-15 files) and the same single `TODO`. |
 
-In project mode you get a real little codebase — CLI entry, domain types, service
-layer, wiring — where **everything works except one `TODO`**. You implement that
-piece (the algorithm) and `node tests/runner.mjs` verifies the app end-to-end.
+In project mode you get a real little codebase — CLI entry or web server, domain
+types, service layer, wiring — where **everything works except one `TODO`**. You
+implement that piece (the algorithm) and `node tests/runner.mjs` verifies the app
+end-to-end.
 
 Project mode is available for **TypeScript, Python, Rust**; the other languages use
 the quick exercise.
 
+**Pick your stack.** In project mode it also asks for a stack:
+
+| Stack | Shape | How it's tested |
+| --- | --- | --- |
+| Vanilla (no framework) | CLI / library | JSON on stdin → JSON on stdout |
+| Express API (Node) | HTTP server | runner starts it and sends HTTP requests |
+| Next.js (React) | route handlers / API | runner starts it and sends HTTP requests |
+| FastAPI (Python) | HTTP server | runner starts it and sends HTTP requests |
+| Agent decides | whatever fits | inferred from the chosen shape |
+
+The folder structure is **not hardcoded** — the agent designs a layout that fits
+the stack and problem (`files`), so it feels like a real repo, not a template.
+
+For server projects, test cases are HTTP requests
+(`{ name, method, path, input, expected, status }`); the runner runs your
+`installCommand`, optional `buildCommand`, boots `startCommand`, waits on
+`healthPath`, then checks each request. For CLI/library projects it stays
+stdin/stdout.
+
 The generated project looks like this:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-leetcode-realworld",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OpenCode plugin that turns a LeetCode problem into a realistic software-engineering assignment, so you practice applying the underlying algorithm instead of solving the puzzle.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -8,8 +8,15 @@ import type { ScaffoldSpec } from "./types";
 
 const testCaseSchema = tool.schema.object({
   name: tool.schema.string().describe("Short description of what the case asserts"),
-  input: tool.schema.any().describe("The single JSON-shaped payload passed to the entry function"),
-  expected: tool.schema.any().describe("The JSON-shaped value the entry function must return"),
+  input: tool.schema.any().optional().describe("stdio: JSON payload. http: JSON request body."),
+  expected: tool.schema.any().optional().describe("Expected JSON result/response body"),
+  method: tool.schema.string().optional().describe("http: method, e.g. POST (default GET)"),
+  path: tool.schema.string().optional().describe("http: request path, e.g. /api/events"),
+  status: tool.schema.number().optional().describe("http: expected status code (default 200)"),
+  headers: tool.schema
+    .record(tool.schema.string(), tool.schema.string())
+    .optional()
+    .describe("http: extra request headers"),
 });
 
 export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
@@ -119,11 +126,28 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
       runCommand: tool.schema
         .string()
         .optional()
-        .describe("Project mode: command that runs one case (JSON on stdin, JSON on stdout)"),
+        .describe("stdio project: command that runs one case (JSON on stdin, JSON on stdout)"),
       buildCommand: tool.schema
         .string()
         .optional()
-        .describe("Project mode: optional one-time build command (compiled languages)"),
+        .describe("Project mode: optional one-time build command (e.g. `cargo build`)"),
+      installCommand: tool.schema
+        .string()
+        .optional()
+        .describe("Project mode: optional one-time install command (e.g. `npm install`)"),
+      startCommand: tool.schema
+        .string()
+        .optional()
+        .describe("http project: command that starts the server (enables HTTP test mode)"),
+      port: tool.schema.number().optional().describe("http project: server port (default 3000)"),
+      healthPath: tool.schema
+        .string()
+        .optional()
+        .describe("http project: readiness path the runner polls (default /)"),
+      stack: tool.schema
+        .string()
+        .optional()
+        .describe("Free-form stack label, e.g. express, nextjs, fastapi, vanilla"),
     },
     async execute(rawArgs, context) {
       const spec = rawArgs as ScaffoldSpec;
@@ -153,7 +177,7 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
         `Created a real-world practice project at ${relative}`,
         "",
         `Title: ${result.title}`,
-        `Mode: ${result.mode}${result.mode === "project" ? " (implement the marked TODO)" : ""}`,
+        `Mode: ${result.mode}${result.mode === "project" ? ` (${result.kind}${result.stack ? `, ${result.stack}` : ""})` : ""}`,
         `Language: ${result.languageName} (${result.runtime})`,
         `Files (${result.files.length}):`,
         ...result.files.map((file) => `  - ${file}`),

package/src/prompt.ts

@@ -16,6 +16,15 @@ export const SUPPORTED_LANGUAGES = [
 /** Languages that can receive a full multi-file project. */
 export const PROJECT_LANGUAGES = ["TypeScript", "Python", "Rust"];
 
+/** Stacks offered in project mode. */
+export const STACKS = [
+  "Vanilla (no framework)",
+  "Express API (Node)",
+  "Next.js (React)",
+  "FastAPI (Python)",
+  "Agent decides",
+];
+
 /**
  * The `/practice` command prompt. It orchestrates the two plugin tools and is
  * deliberately opinionated: the whole value of this plugin is that the learner
@@ -35,107 +44,110 @@ Recognise any of these (all optional):
 - tags: topic names or slugs, e.g. "graph" or "dynamic-programming,sliding-window"
 - a specific problem id or slug, e.g. "two-sum" or "1"
 - language: a supported language name or alias (below)
-- scope: "single" | "mini" | "full"  (how they want to start)
+- scope: "single" | "mini" | "full"
+- stack: a stack name, e.g. "express", "nextjs", "fastapi", "vanilla"
 
 Mapping rules:
 - A word that names a topic (array, string, graph, tree, dp/dynamic-programming,
   sliding-window, two-pointers, greedy, ...) is a TAG. Pass it to \`leetcode_fetch\`
-  as \`tags\` (an array of slugs, e.g. \`["array"]\`).
-- Only pass \`idOrSlug\` when the argument is a number or a known problem slug
-  (e.g. "1", "two-sum"). Never pass a topic name as \`idOrSlug\`.
-- When the user gives a tag, it MUST be respected. After fetching, if the problem's
-  topics do not include the requested tag, the fetch is wrong: retry with the tag.
+  as \`tags\` (array of slugs).
+- Only pass \`idOrSlug\` for a number or known slug (e.g. "1", "two-sum").
+- When a tag is given it MUST be respected; if the fetched topics lack it, retry.
 
 ## 2. Ask how they want to start (use the \`question\` tool)
 
-Step A — if the language and/or difficulty are missing, ask for them in one
-\`question\` call. Supported languages: ${SUPPORTED_LANGUAGES.join(", ")}.
-Offer difficulty options "Easy", "Medium" (recommended), "Hard".
+Step A — if language and/or difficulty are missing, ask in one \`question\` call.
+Languages: ${SUPPORTED_LANGUAGES.join(", ")}. Difficulty options: "Easy",
+"Medium" (recommended), "Hard".
+
+Step B — scope. Full projects are only for ${PROJECT_LANGUAGES.join(", ")}.
+- If the language is one of those AND scope was not given, ask a SECOND question
+  "How do you want to start?" with: "Quick exercise" (one function),
+  "Mini project" (~3-6 files), "Fuller project" (~6-15 files).
+- Otherwise skip it.
 
-Step B — decide the *scope*. Full multi-file projects are only available for
-${PROJECT_LANGUAGES.join(", ")}.
-- If the chosen language is one of those AND scope was not given, make a SECOND
-  \`question\` call titled "How do you want to start?" with these options:
-  - "Quick exercise" — one focused function with a JSON-in/JSON-out contract.
-  - "Mini project" — a small multi-file app (~3-6 files) with the algorithm at its core.
-  - "Fuller project" — a multi-file app with more realistic layers (~6-15 files).
-- Otherwise (other language, or scope already given) skip this question.
+Step C — stack. Only when the scope is a project (not "Quick exercise"):
+- If the stack was not given, ask a THIRD \`question\`: "Which stack?" with:
+  ${STACKS.map((s) => `"${s}"`).join(", ")}.
+- Pick sensible stacks: Express/Next.js for TypeScript, FastAPI for Python,
+  "Vanilla" or an HTTP service for Rust.
 
-Wait for the answers. Do not guess.
+Wait for answers. Do not guess.
 
 ## 3. Fetch the source problem (private)
-Call the \`leetcode_fetch\` tool with the difficulty, and pass any requested topic
-as \`tags\` (array of slugs). Verify the returned topics include every requested
-tag; if not, retry. The fetched statement is for YOUR reasoning only. Never paste
-it, paraphrase it closely, or name its source anywhere in the generated project.
+Call \`leetcode_fetch\` with the difficulty, passing topics as \`tags\`. Verify the
+returned topics include every requested tag; retry if not. The statement is for
+YOUR reasoning only — never paste it or name its source anywhere.
 
 ## 4. Derive the principle
-Identify the underlying algorithmic idea (e.g. sliding window, heap-based
-scheduling, union-find, DP over intervals). Do not carry over the problem's
-fiction (arrays of "nums", "target", etc.).
+Identify the underlying algorithmic idea. Do not carry over the problem's fiction.
 
 ## 5. Build the assignment
-Design a plausible product/business task that genuinely needs that principle. Good
-domains: observability, payments/ledgering, logistics, rate limiting, access
-control, search, feature flags, data reconciliation, scheduling.
-
-Then call \`leetcode_scaffold\`. There are two shapes:
-
-### A) mode = "single"  (Quick exercise)
-- One entry point with a JSON-in / JSON-out contract.
-- Do NOT provide \`starterCode\`: the plugin generates a typed starter (type-safe
-  languages) or a documented one (dynamic languages) inferred from your test cases,
-  so make the first few cases representative (vary fields to expose optionals).
-- Spec: mode, title, scenario, pattern, difficulty, language, requirements,
-  edgeCases, publicTests (5-8), hiddenTests (6-12 incl. empty + large), task optional,
-  sourceSlug, sourceTitle.
-
-### B) mode = "project"  (only ${PROJECT_LANGUAGES.join(", ")})
-Build a small but real application where the algorithm is the piece the learner
-implements. You author the whole tree and pass it as \`files\`.
-- Provide a working CLI entry (e.g. \`src/cli.ts\`, \`src/cli.py\`, or \`src/main.rs\`)
-  that reads ONE JSON value on stdin and writes ONE JSON value on stdout. Tests
-  drive this entry end-to-end.
-- Put the algorithm behind a single, clearly marked \`TODO\` in a domain/service file
-  (e.g. \`// TODO: implement ...\`). Everything else — argument/stdin parsing, domain
-  models/types, wiring, config, a repository or helper — must be complete and runnable
-  so that the ONLY thing missing is that TODO.
-- Keep the surrounding code real but not algorithm-heavy: parsing, types, plumbing.
-- Respect the requested size: mini ~3-6 files, fuller ~6-15 files.
-- Provide \`runCommand\` (runs one case) and, for compiled languages, \`buildCommand\`
-  (e.g. Rust: \`cargo build\`; then \`runCommand: ./target/debug/<bin>\`).
-- Provide \`task\`: a short markdown brief naming the file and function to implement.
-- Include everything needed to build/run (package.json/tsconfig, Cargo.toml, etc.).
-- Import/runtime correctness (the tests run your \`runCommand\`):
-  - TypeScript: relative imports MUST include the \`.ts\` extension
-    (\`import { x } from "./service.ts"\`) because the app runs under Node ESM type
-    stripping, which does not resolve extensionless specifiers.
-  - Python: make imports work when the entry runs directly (\`python3 src/cli.py\`);
-    same-directory modules or a small \`sys.path\` adjustment are both fine.
-  - Rust: declare internal modules with \`mod ...;\` and keep them under \`src/\`.
-- Do NOT implement the TODO and do not reveal the algorithm in comments.
+When the spec is ready, call the \`leetcode_scaffold\` tool. The two shapes differ:
+
+### A) scope = Quick exercise  -> mode "single"
+One entry point, JSON-in / JSON-out. Do NOT provide \`starterCode\` (the plugin
+generates typed/documented starters from your test cases). Spec: mode, title,
+scenario, pattern, difficulty, language, requirements, edgeCases, publicTests
+(5-8), hiddenTests (6-12), sourceSlug, sourceTitle.
+
+### B) scope = Mini/Fuller project  -> mode "project" (${PROJECT_LANGUAGES.join(", ")})
+Build a REAL app in the chosen stack. The folder structure is entirely up to you
+— it is fluid, there is no template. The learner must implement ONE marked TODO
+that contains the algorithm; the rest must build and run.
+
+Design:
+- Create a genuine feature the algorithm powers (an endpoint, command, job, or
+  module), embedded in a believable app with a few real layers (entry, routing or
+  CLI, domain/service, models/types, small helpers). Respect the size: mini ~3-6
+  files, fuller ~6-15 files.
+- Leave exactly one \`TODO\` where the algorithm goes. It must be the ONLY thing
+  missing. Everything else compiles/runs.
+- Choose the interface based on the stack:
+
+  * Web/API stacks (Express, Next.js, FastAPI, any HTTP server): provide
+    \`startCommand\`, \`port\`, \`healthPath\` (a route that returns 200), and use
+    **HTTP test cases**. Every case is: { name, method, path, input (JSON body),
+    expected (JSON response body), status? }. Add install/build commands as needed
+    (\`installCommand\`, e.g. "npm install" / "python -m pip install -r requirements.txt";
+    \`buildCommand\` only if a build is required). The runner starts the server,
+    polls the health path, then sends the requests.
+  * Non-web stacks (CLI/library): provide \`runCommand\` (reads ONE JSON value on
+    stdin, writes ONE JSON value on stdout) and use stdio cases
+    { name, input, expected }.
+
+- Include everything needed to build/run you write as \`files\` (manifests, config,
+  source). No hidden dependencies beyond \`installCommand\`.
+- Import/runtime correctness:
+  - TypeScript under Node ESM type-stripping: relative imports MUST include the
+    \`.ts\` extension (\`import { x } from "./service.ts"\`). If you use a bundler/dev
+    server (Next.js), follow that stack's conventions instead.
+  - Python: make imports work when the entry runs as given by \`startCommand\`/\`runCommand\`.
+  - Rust: internal modules via \`mod ...;\` under \`src/\`.
+- Provide \`task\`: a short markdown brief naming the file(s) and function/route to implement.
+- Do NOT implement the TODO and do not reveal the algorithm in comments or commit messages.
 
 Both shapes:
-- requirements: concrete, testable bullet points
-- edgeCases: tricky situations the solution must handle
-- publicTests / hiddenTests: JSON-serialisable \`{ "name": string, "input": any, "expected": any }\`.
-  Every \`expected\` must be correct for the described rules; public and hidden must not overlap.
-- sourceSlug / sourceTitle: provenance ONLY, never surfaced.
+- requirements / edgeCases: concrete and testable
+- publicTests (5-8) and hiddenTests (6-12) as JSON-serialisable objects. Every
+  \`expected\` must be correct; public and hidden must not overlap. Include an
+  empty/degenerate case and a larger case.
+- \`sourceSlug\` / \`sourceTitle\`: provenance ONLY, never surfaced.
 
 ## 6. Rules (non-negotiable)
 - Titles, scenarios, requirements, comments, file contents and test names MUST NOT
   mention LeetCode, its title, its slug, or any coding-practice site. The tool
-  rejects leaks (including inside \`files\`).
-- NEVER implement the algorithm (single mode: leave the entry unimplemented;
-  project mode: leave the TODO unimplemented). The learner does that.
+  rejects leaks, including inside \`files\`.
+- NEVER implement the algorithm (single: leave the entry unimplemented; project:
+  leave the TODO unimplemented).
 - Do not reveal the fetched problem or the original examples.
 
 ## 7. After scaffolding
 Report back with, in order:
-1. One short paragraph describing the assignment as a real task (no source spoilers).
-2. The project path, mode, and language.
+1. One short paragraph describing the assignment as a real task (no spoilers).
+2. The project path, mode, stack, and language.
 3. The exact command to run the tests (\`node tests/runner.mjs\`).
-4. For project mode: which file/function holds the TODO.
+4. For project mode: the file(s) and function/route holding the TODO.
 5. Note that \`tests/hidden/cases.json\` holds extra acceptance cases they should not edit.
 Then stop. If the learner asks for help, give guiding hints and ask questions
 rather than writing the algorithm for them.

package/src/scaffold.ts

@@ -37,7 +37,7 @@ function json(value: unknown, indent = 2): string {
 }
 
 const RUNNER = String.raw`#!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -45,6 +45,8 @@ import { fileURLToPath } from "node:url";
 const testsDir = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(testsDir, "..");
 const harness = JSON.parse(readFileSync(path.join(root, "harness.json"), "utf8"));
+const kind = harness.kind === "http" ? "http" : "stdio";
+const baseUrl = () => "http://127.0.0.1:" + (harness.port || 3000);
 
 function canonical(value) {
   if (Array.isArray(value)) return value.map(canonical);
@@ -60,12 +62,20 @@ function same(a, b) {
   return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 }
 
-function runCase(input) {
+function runOnce(command) {
+  const result = spawnSync(command, { cwd: root, shell: true, stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error("\nCommand failed: " + command);
+    process.exit(1);
+  }
+}
+
+function runStdio(input) {
   const result = spawnSync(harness.run, {
     cwd: root,
     shell: true,
     encoding: "utf8",
-    input: JSON.stringify(input),
+    input: JSON.stringify(input === undefined ? null : input),
     timeout: 30000,
   });
   if (result.error) throw result.error;
@@ -77,46 +87,108 @@ function runCase(input) {
   return text === "" ? null : JSON.parse(text);
 }
 
-if (harness.build) {
-  const build = spawnSync(harness.build, { cwd: root, shell: true, stdio: "inherit" });
-  if (build.status !== 0) {
-    console.error("\nBuild failed.");
-    process.exit(1);
+async function waitForServer() {
+  const health = harness.healthPath || "/";
+  const deadline = Date.now() + 40000;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(baseUrl() + health);
+      if (response.status < 500) return;
+    } catch (error) {
+      /* server not up yet */
+    }
+    await new Promise((resolve) => setTimeout(resolve, 400));
   }
+  throw new Error("server did not become ready at " + baseUrl() + health);
 }
 
-const onlyPublic = process.argv.includes("--public");
-const suites = onlyPublic ? ["public"] : ["public", "hidden"];
-let passed = 0;
-let failed = 0;
+async function runHttp(testCase) {
+  const method = (testCase.method || "GET").toUpperCase();
+  const init = {
+    method: method,
+    headers: Object.assign({ "content-type": "application/json" }, testCase.headers || {}),
+  };
+  if (testCase.input !== undefined && method !== "GET" && method !== "HEAD") {
+    init.body = JSON.stringify(testCase.input);
+  }
+  const response = await fetch(baseUrl() + (testCase.path || "/"), init);
+  const expectedStatus = testCase.status || 200;
+  if (response.status !== expectedStatus) {
+    throw new Error("expected HTTP " + expectedStatus + " but got " + response.status);
+  }
+  const text = (await response.text()).trim();
+  return text === "" ? null : JSON.parse(text);
+}
 
-for (const suite of suites) {
-  const cases = JSON.parse(readFileSync(path.join(root, "tests", suite, "cases.json"), "utf8"));
-  console.log("\n" + suite + " (" + cases.length + " cases)");
-  for (const testCase of cases) {
+function stopServer(server) {
+  if (server && server.pid) {
     try {
-      const received = runCase(testCase.input);
-      if (same(received, testCase.expected)) {
-        passed += 1;
-        console.log("  PASS  " + testCase.name);
-      } else {
-        failed += 1;
-        console.log("  FAIL  " + testCase.name);
-        console.log("        expected: " + JSON.stringify(testCase.expected));
-        console.log("        received: " + JSON.stringify(received));
+      process.kill(-server.pid, "SIGTERM");
+    } catch (error) {
+      try {
+        server.kill();
+      } catch (inner) {
+        /* ignore */
       }
+    }
+  }
+}
+
+async function main() {
+  if (harness.install) runOnce(harness.install);
+  if (harness.build) runOnce(harness.build);
+
+  let server;
+  if (kind === "http") {
+    server = spawn(harness.start, { cwd: root, shell: true, stdio: "inherit", detached: true });
+    try {
+      await waitForServer();
     } catch (error) {
-      failed += 1;
-      console.log("  ERROR " + testCase.name);
-      for (const line of String(error.message).split("\n")) {
-        console.log("        " + line);
+      console.error(String(error.message));
+      stopServer(server);
+      process.exit(1);
+    }
+  }
+
+  const onlyPublic = process.argv.includes("--public");
+  const suites = onlyPublic ? ["public"] : ["public", "hidden"];
+  let passed = 0;
+  let failed = 0;
+
+  try {
+    for (const suite of suites) {
+      const cases = JSON.parse(readFileSync(path.join(root, "tests", suite, "cases.json"), "utf8"));
+      console.log("\n" + suite + " (" + cases.length + " cases)");
+      for (const testCase of cases) {
+        try {
+          const received = kind === "http" ? await runHttp(testCase) : runStdio(testCase.input);
+          if (same(received, testCase.expected)) {
+            passed += 1;
+            console.log("  PASS  " + testCase.name);
+          } else {
+            failed += 1;
+            console.log("  FAIL  " + testCase.name);
+            console.log("        expected: " + JSON.stringify(testCase.expected));
+            console.log("        received: " + JSON.stringify(received));
+          }
+        } catch (error) {
+          failed += 1;
+          console.log("  ERROR " + testCase.name);
+          for (const line of String(error.message).split("\n")) {
+            console.log("        " + line);
+          }
+        }
       }
     }
+  } finally {
+    stopServer(server);
   }
+
+  console.log("\n" + passed + " passed, " + failed + " failed");
+  process.exit(failed === 0 ? 0 : 1);
 }
 
-console.log("\n" + passed + " passed, " + failed + " failed");
-process.exit(failed === 0 ? 0 : 1);
+main();
 `;
 
 function requirementsSection(spec: ScaffoldSpec): string {
@@ -329,8 +401,7 @@ node tests/runner.mjs --public   # visible cases only
 
 Requires ${adapter.runtime}.
 
-The app is invoked once per case as \`${spec.runCommand}\`: it reads **one JSON value
-on stdin** and must write **one JSON value on stdout**. Debug output goes to stderr.
+The tests ${spec.startCommand ? `start the server (\`${spec.startCommand}\`) and send HTTP requests to port ${spec.port ?? 3000}` : `invoke the app once per case as \`${spec.runCommand}\``}. ${spec.startCommand ? "Each case is an HTTP request; the JSON response body is compared." : "It reads **one JSON value on stdin** and must write **one JSON value on stdout**."} Debug output goes to stderr.
 
 ## Files
 
@@ -357,9 +428,7 @@ ${task}
 
 ## Interface
 
-The application is invoked as \`${spec.runCommand}\`. It reads **one JSON value from
-stdin** and must write **one JSON value to stdout**. Only stdout is compared; use
-stderr for logs.
+${spec.startCommand ? `The application is a server. It is started with \`${spec.startCommand}\` on port ${spec.port ?? 3000}. The tests send HTTP requests (method + path + JSON body) and compare the JSON response body.` : `The application is invoked as \`${spec.runCommand}\`. It reads **one JSON value from stdin** and must write **one JSON value to stdout**.`} Only the JSON is compared; use stderr for logs.
 
 ## Definition of done
 
@@ -395,7 +464,16 @@ function buildProjectFiles(
     {
       relative: "harness.json",
       contents:
-        json({ build: spec.buildCommand ?? adapter.build(ctx), run: spec.runCommand }) + "\n",
+        json({
+          kind: spec.startCommand ? "http" : "stdio",
+          stack: spec.stack ?? null,
+          install: spec.installCommand ?? null,
+          build: spec.buildCommand ?? (spec.startCommand ? null : adapter.build(ctx)),
+          run: spec.startCommand ? null : spec.runCommand,
+          start: spec.startCommand ?? null,
+          port: spec.startCommand ? spec.port ?? 3000 : null,
+          healthPath: spec.startCommand ? spec.healthPath ?? "/" : null,
+        }) + "\n",
     },
     { relative: "tests/runner.mjs", contents: RUNNER },
     { relative: "tests/public/cases.json", contents: casesFile(spec.publicTests ?? []) },
@@ -450,8 +528,10 @@ export async function scaffold(
     if (!normalized.files || normalized.files.length === 0) {
       throw new Error("Project mode requires a `files` list (the full file tree).");
     }
-    if (!normalized.runCommand) {
-      throw new Error("Project mode requires a `runCommand` (run one case, JSON on stdin/stdout).");
+    if (!normalized.startCommand && !normalized.runCommand) {
+      throw new Error(
+        "Project mode requires either `runCommand` (stdio) or `startCommand` (http server).",
+      );
     }
   }
 
@@ -478,6 +558,8 @@ export async function scaffold(
     languageName: adapter.name,
     runtime: adapter.runtime,
     mode,
+    kind: normalized.startCommand ? "http" : "stdio",
+    stack: normalized.stack,
     files: files.map((file) => file.relative).sort(),
     runCommand: check,
     checkCommand: check,

package/src/types.ts

@@ -40,10 +40,22 @@ export interface NormalizedProblem {
 
 export interface TestCase {
   name: string;
-  input: unknown;
-  expected: unknown;
+  /** stdio: the JSON payload. http: the request body (ignored for GET/HEAD). */
+  input?: unknown;
+  /** stdio: expected result. http: expected JSON response body. */
+  expected?: unknown;
+  /** http only: HTTP method (default GET). */
+  method?: string;
+  /** http only: request path, e.g. "/api/events" (default "/"). */
+  path?: string;
+  /** http only: expected status code (default 200). */
+  status?: number;
+  /** http only: extra request headers. */
+  headers?: Record<string, string>;
 }
 
+export type HarnessKind = "stdio" | "http";
+
 export interface FileEntry {
   relative: string;
   contents: string;
@@ -65,6 +77,8 @@ export type PracticeMode = "single" | "project";
 export interface ScaffoldSpec {
   /** `single` = one JSON-in/out function. `project` = a multi-file app. */
   mode?: PracticeMode;
+  /** Free-form stack label, e.g. "express", "nextjs", "fastapi", "vanilla". */
+  stack?: string;
   /** kebab-case directory name. Derived from `title` when omitted. */
   projectName?: string;
   /** Human title of the *real-world* project, e.g. "Realtime Dedup Pipeline". */
@@ -94,10 +108,18 @@ export interface ScaffoldSpec {
   files?: ProjectFile[];
   /** Markdown brief for the learner: what to implement and where. */
   task?: string;
-  /** Command that runs one test case (JSON on stdin, JSON on stdout). */
+  /** stdio project: command that runs one case (JSON stdin -> JSON stdout). */
   runCommand?: string;
-  /** Optional one-time build command (compiled languages). */
+  /** Optional one-time install command (e.g. `npm install`, `pip install -r req.txt`). */
+  installCommand?: string;
+  /** Optional one-time build command (e.g. `cargo build`, `npm run build`). */
   buildCommand?: string;
+  /** http project: command that starts the server. */
+  startCommand?: string;
+  /** http project: port the server listens on (default 3000). */
+  port?: number;
+  /** http project: path used to poll readiness (default "/"). */
+  healthPath?: string;
 }
 
 export interface ScaffoldResult {
@@ -107,6 +129,8 @@ export interface ScaffoldResult {
   languageName: string;
   runtime: string;
   mode: PracticeMode;
+  kind: HarnessKind;
+  stack?: string;
   files: string[];
   runCommand: string;
   checkCommand: string;