opencode-leetcode-realworld 0.3.0 → 0.5.0

package/README.md

@@ -76,6 +76,7 @@ Options can be given in any order; the command figures out which is which.
 | `tags` | One or more topic tags, comma-separated (e.g. `graph` or `dynamic-programming,sliding-window`) | any | Nudges which underlying algorithm and real-world domain you get. |
 | `<id-or-slug>` | A problem number or slug (e.g. `1`, `two-sum`) | random | Derive the assignment from one specific source problem. |
 | `language` | A supported language or alias (see below) | **asks you** | Language of the generated project and tests. |
+| `scope` | `single` \| `mini` \| `full` | **asks you** | How big the assignment is (see Two modes). |
 
 If you leave the language (or difficulty) out, opencode **asks you** with a
 multiple-choice question before generating anything.
@@ -150,17 +151,54 @@ they tend to produce:
 ```
 /practice
    │
-   ├─ (agent)             if language/difficulty are missing, ask you via the `question` tool
+   ├─ (agent)             ask you for language/difficulty, then how you want to start
    │
    ├─ leetcode_fetch      fetch a problem from the LeetCode API (private reasoning input)
    │
    ├─ (agent)             derive the principle -> invent a real-world scenario
    │
-   ├─ leetcode_scaffold   write README / PROJECT / starter / tests, reject any leak
+   ├─ leetcode_scaffold   write the exercises(s): one function, or a multi-file app
    │
    └─ guard hooks         block reading hidden tests + provenance, keep the exercise honest
 ```
 
+## Two modes
+
+`/practice` asks **how you want to start**, and the answer changes what gets built:
+
+| Scope | What you get |
+| --- | --- |
+| **Quick exercise** | One entry point with a JSON-in / JSON-out contract (any language). |
+| **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 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.3.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 }) => {
@@ -71,9 +78,15 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
 
   const scaffoldTool = tool({
     description:
-      "Create a real-world practice project from a spec (scenario, requirements, starter, tests). " +
+      "Create a real-world practice project from a spec. " +
+      "Use mode \"single\" for one JSON-in/out function (any language) or mode \"project\" " +
+      "(typescript, python, rust) for a multi-file app where one TODO must be implemented. " +
       "Rejects any spec that leaks the original problem, its title, slug, or a coding-practice site name.",
     args: {
+      mode: tool.schema
+        .enum(["single", "project"])
+        .default("single")
+        .describe("single = one function; project = multi-file app (ts/python/rust)"),
       title: tool.schema.string().describe("Real-world project title (no coding-practice words)"),
       scenario: tool.schema.string().describe("Business context, written like a real ticket"),
       pattern: tool.schema.string().describe("Underlying algorithmic principle (internal only)"),
@@ -102,6 +115,39 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
       outDir: tool.schema.string().optional().describe("Target directory, relative to the session directory"),
       sourceSlug: tool.schema.string().optional().describe("Provenance only; never surfaced"),
       sourceTitle: tool.schema.string().optional().describe("Provenance only; never surfaced"),
+      task: tool.schema
+        .string()
+        .optional()
+        .describe("Project mode: markdown brief telling the learner what to implement and where"),
+      files: tool.schema
+        .array(tool.schema.object({ path: tool.schema.string(), content: tool.schema.string() }))
+        .optional()
+        .describe("Project mode: the full file tree, leaving one TODO to implement"),
+      runCommand: tool.schema
+        .string()
+        .optional()
+        .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 (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;
@@ -131,6 +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" ? ` (${result.kind}${result.stack ? `, ${result.stack}` : ""})` : ""}`,
         `Language: ${result.languageName} (${result.runtime})`,
         `Files (${result.files.length}):`,
         ...result.files.map((file) => `  - ${file}`),

package/src/patterns.ts

@@ -92,11 +92,12 @@ function textsFromSpec(spec: ScaffoldSpec): Array<[string, string]> {
   push("scenario", spec.scenario);
   push("pattern", spec.pattern);
   push("functionName", spec.functionName);
-  push("starterCode", spec.starterCode);
+  push("task", spec.task);
   (spec.requirements ?? []).forEach((req, i) => push(`requirements[${i}]`, req));
   (spec.edgeCases ?? []).forEach((edge, i) => push(`edgeCases[${i}]`, edge));
   (spec.publicTests ?? []).forEach((test, i) => push(`publicTests[${i}].name`, test.name));
   (spec.hiddenTests ?? []).forEach((test, i) => push(`hiddenTests[${i}].name`, test.name));
+  (spec.files ?? []).forEach((file, i) => push(`files[${i}] (${file.path})`, file.content));
   return entries;
 }
 

package/src/prompt.ts

@@ -13,6 +13,18 @@ export const SUPPORTED_LANGUAGES = [
   "Swift",
 ];
 
+/** 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
@@ -32,92 +44,111 @@ 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"
+- 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 language and/or difficulty are missing, ask in one \`question\` call.
+Languages: ${SUPPORTED_LANGUAGES.join(", ")}. Difficulty options: "Easy",
+"Medium" (recommended), "Hard".
 
-## 2. Ask when unclear (use the \`question\` tool)
-Supported languages: ${SUPPORTED_LANGUAGES.join(", ")}.
+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.
 
-- If the user did NOT specify a language, call the \`question\` tool and ask which
-  language they want to practice, offering these as options:
-  ${SUPPORTED_LANGUAGES.map((name) => `"${name}"`).join(", ")}.
-- If the user did NOT specify a difficulty, include a second question in the SAME
-  \`question\` call offering "Easy", "Medium" (recommended), and "Hard".
-- Wait for the answers. Do not guess and do not default silently.
+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.
 
-If the user did specify values, skip the corresponding question. Only ask at all
-when something is missing.
+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) — not as \`idOrSlug\`. 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.).
-
-## 5. Invent a real engineering scenario
-Design a plausible product/business task that genuinely needs that principle. Good
-domains: observability pipelines, payments/ledgering, logistics, rate limiting,
-access control, search, feature flags, data reconciliation, scheduling.
-The scenario must read like a ticket from a real team: who needs it, why, and what
-"correct" means.
-
-The assignment has ONE entry point with a JSON-in / JSON-out contract:
-- It receives a single JSON value (usually an object describing a request).
-- It returns a single JSON value (a response or result).
-This is how real services, CLIs and jobs exchange data, and it lets the same test
-harness verify any language.
-
-Call the tool \`leetcode_scaffold\` with a spec containing:
-- title: real-world project title (no coding-practice words)
-- scenario: 1-3 paragraphs of business context
-- pattern: the underlying principle (internal only)
-- language: the language the user chose (use the canonical id, e.g. "typescript",
-  "javascript", "python", "ruby", "php", "go", "rust", "csharp", "swift")
-- requirements: concrete, testable bullet points
-- edgeCases: tricky situations the solution must handle
-- Do NOT provide starterCode. Omit it so the plugin can generate a starter that
-  reflects the real types: type-safe languages get typed interfaces/structs and a
-  typed signature; dynamic languages get a documented input/output format comment.
-  The generated types are inferred from your publicTests/hiddenTests, so make the
-  first few cases representative of the full input shape (and vary fields so
-  optional ones are detected).
-- publicTests: 5-8 visible cases that illustrate the contract
-- hiddenTests: 6-12 acceptance cases, including edge cases, boundary values, an
-  empty/degenerate input, and at least one larger input
-- sourceSlug / sourceTitle: for internal provenance ONLY (never surfaced)
-
-Test cases must be JSON-serialisable: \`{ "name": string, "input": any, "expected": any }\`.
-Make sure every \`expected\` value is actually correct for the described rules, and
-that public and hidden cases do not overlap.
+Identify the underlying algorithmic idea. Do not carry over the problem's fiction.
+
+## 5. Build the assignment
+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 / 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)
-- The generated title, scenario, requirements, comments, and test names MUST NOT
-  mention LeetCode, its title, its slug, or any coding-practice site. The
-  \`leetcode_scaffold\` tool will reject the spec if it does.
-- DO NOT implement the solution. Your job ends when the scaffold is written. The
-  learner implements the solution file themselves.
+- 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: leave the entry unimplemented; project:
+  leave the TODO unimplemented).
 - Do not reveal the fetched problem or the original examples.
-- If the tool reports a leak, rewrite the offending fields and retry.
 
 ## 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 and chosen 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. Note that \`tests/hidden/cases.json\` holds extra acceptance cases they should not edit.
+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 {
@@ -232,9 +304,15 @@ tests/hidden/
 .practice-meta.json
 `;
 
-function metaFor(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
+function metaFor(
+  spec: ScaffoldSpec,
+  names: ResolvedNames,
+  language: LanguageId,
+  mode: "single" | "project" = "single",
+): string {
   return (
     json({
+      mode,
       title: names.title,
       functionName: names.functionName,
       language,
@@ -289,6 +367,125 @@ function buildFiles(spec: ScaffoldSpec, names: ResolvedNames, language: Language
   return files;
 }
 
+/** Languages that support full multi-file project mode. */
+export const PROJECT_LANGUAGES = new Set<LanguageId>(["typescript", "python", "rust"]);
+
+function sanitizeRelative(value: string): string {
+  const normalized = value.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (normalized.includes("..") || /^[a-zA-Z]:/.test(normalized)) {
+    throw new Error(`Refusing to write outside the project directory: "${value}"`);
+  }
+  return normalized;
+}
+
+function projectReadme(
+  names: ResolvedNames,
+  spec: ScaffoldSpec,
+  language: LanguageId,
+): string {
+  const adapter = getLanguage(language);
+  const fileList = (spec.files ?? [])
+    .map((file) => `  ${sanitizeRelative(file.path)}`)
+    .join("\n");
+  return `# ${names.title}
+
+This is a small application, not a single function. Read \`PROJECT.md\` for the
+brief, find the marked \`TODO\`, and implement the behaviour it needs.
+
+## Run the checks
+
+\`\`\`bash
+node tests/runner.mjs            # all cases
+node tests/runner.mjs --public   # visible cases only
+\`\`\`
+
+Requires ${adapter.runtime}.
+
+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
+
+\`\`\`
+${fileList}
+\`\`\`
+`;
+}
+
+function projectModeDoc(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
+  const task = spec.task?.trim() || "Find the `TODO` in the source and implement it.";
+  return `# ${names.title}
+
+## Scenario
+
+${spec.scenario.trim()}
+
+${exampleSection(spec)}
+${requirementsSection(spec)}
+${edgeCaseSection(spec)}
+## What to build
+
+${task}
+
+## Interface
+
+${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
+
+- The full test suite passes: \`node tests/runner.mjs\`.
+- The provided code is understood and reused, not bypassed.
+- Edge cases above are handled, not just the happy path.
+`;
+}
+
+function buildProjectFiles(
+  spec: ScaffoldSpec,
+  names: ResolvedNames,
+  language: LanguageId,
+): FileEntry[] {
+  const adapter = getLanguage(language);
+  const cases = [...(spec.publicTests ?? []), ...(spec.hiddenTests ?? [])];
+  const first = cases[0];
+  const ctx: LanguageContext = {
+    projectName: names.projectName,
+    functionName: names.functionName,
+    title: names.title,
+    input: schemaFromSamples(cases.map((test) => test.input)),
+    output: schemaFromSamples(cases.map((test) => test.expected)),
+    inputExample: first?.input ?? null,
+    outputExample: first?.expected ?? null,
+  };
+
+  const files: FileEntry[] = [
+    { relative: "README.md", contents: projectReadme(names, spec, language) },
+    { relative: "PROJECT.md", contents: projectModeDoc(spec, names, language) },
+    { relative: ".gitignore", contents: PROJECT_GITIGNORE },
+    { relative: ".practice-meta.json", contents: metaFor(spec, names, language, "project") },
+    {
+      relative: "harness.json",
+      contents:
+        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 ?? []) },
+    { relative: "tests/hidden/cases.json", contents: casesFile(spec.hiddenTests ?? []) },
+  ];
+
+  for (const file of spec.files ?? []) {
+    files.push({ relative: sanitizeRelative(file.path), contents: file.content });
+  }
+  return files;
+}
+
 export interface ScaffoldOptions {
   /** Base directory to resolve relative paths against (the session directory). */
   directory: string;
@@ -316,13 +513,37 @@ export async function scaffold(
 
   assertNoLeak(normalized);
 
+  const mode = normalized.mode === "project" ? "project" : "single";
+
   const adapter = getLanguage(language);
   const names = resolveNames(normalized);
+
+  if (mode === "project") {
+    if (!PROJECT_LANGUAGES.has(language)) {
+      throw new Error(
+        `Project mode is only supported for: ${[...PROJECT_LANGUAGES].join(", ")}. ` +
+          `Use mode "single" for ${adapter.name}.`,
+      );
+    }
+    if (!normalized.files || normalized.files.length === 0) {
+      throw new Error("Project mode requires a `files` list (the full file tree).");
+    }
+    if (!normalized.startCommand && !normalized.runCommand) {
+      throw new Error(
+        "Project mode requires either `runCommand` (stdio) or `startCommand` (http server).",
+      );
+    }
+  }
+
   const target = normalized.outDir
     ? path.resolve(options.directory, normalized.outDir)
     : path.resolve(options.directory, ".practice", names.projectName);
 
-  const files = buildFiles(normalized, names, language);
+  const files =
+    mode === "project"
+      ? buildProjectFiles(normalized, names, language)
+      : buildFiles(normalized, names, language);
+
   for (const file of files) {
     const destination = path.join(target, file.relative);
     await mkdir(path.dirname(destination), { recursive: true });
@@ -336,6 +557,9 @@ export async function scaffold(
     language,
     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,21 +40,45 @@ 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;
 }
 
+/** A file the agent authored for a multi-file project. */
+export interface ProjectFile {
+  path: string;
+  content: string;
+}
+
+export type PracticeMode = "single" | "project";
+
 /**
  * The contract the agent fills in after it has decided on a real-world scenario.
  * None of these fields may reference LeetCode: `scaffold()` calls `assertNoLeak`
  * before writing anything to disk.
  */
 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". */
@@ -69,7 +93,7 @@ export interface ScaffoldSpec {
   functionName?: string;
   requirements?: string[];
   edgeCases?: string[];
-  /** Optional starter implementation. A TODO stub is generated when omitted. */
+  /** Optional starter implementation (single mode). A TODO stub is generated when omitted. */
   starterCode?: string;
   publicTests?: TestCase[];
   hiddenTests?: TestCase[];
@@ -78,6 +102,24 @@ export interface ScaffoldSpec {
   /** Internal provenance, stored in `.practice-meta.json` only. Never leaked. */
   sourceSlug?: string;
   sourceTitle?: string;
+
+  // --- project mode -------------------------------------------------------
+  /** The full file tree for a project-mode assignment. */
+  files?: ProjectFile[];
+  /** Markdown brief for the learner: what to implement and where. */
+  task?: string;
+  /** stdio project: command that runs one case (JSON stdin -> JSON stdout). */
+  runCommand?: string;
+  /** 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 {
@@ -86,6 +128,9 @@ export interface ScaffoldResult {
   language: LanguageId;
   languageName: string;
   runtime: string;
+  mode: PracticeMode;
+  kind: HarnessKind;
+  stack?: string;
   files: string[];
   runCommand: string;
   checkCommand: string;