opencode-leetcode-realworld 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,91 @@ and a test suite. The original problem is never shown to you.
 /practice medium dynamic-programming python
 ```
 
+## Usage
+
+```
+/practice [options]
+```
+
+Options can be given in any order; the command figures out which is which.
+
+### Options
+
+| Option | Accepted values | Default | Description |
+| --- | --- | --- | --- |
+| `difficulty` | `easy` \| `medium` \| `hard` | **asks you** (Medium suggested) | Difficulty of the source problem. |
+| `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. |
+
+If you leave the language (or difficulty) out, opencode **asks you** with a
+multiple-choice question before generating anything.
+
+### Examples
+
+| Command | What you get |
+| --- | --- |
+| `/practice` | Asks for language + difficulty, then builds a random Medium problem. |
+| `/practice easy` | Asks for the language, then an Easy problem. |
+| `/practice hard graph` | Hard problem tagged Graph. |
+| `/practice two-sum` | Asks for the language, then builds from the Two Sum problem. |
+| `/practice medium dynamic-programming python` | Medium DP problem, Python project. |
+| `/practice sliding-window js` | Random sliding-window problem in JavaScript. |
+
+### Supported languages
+
+| Language | Aliases | Runtime needed |
+| --- | --- | --- |
+| TypeScript | `ts` | Node.js 22.6+ |
+| JavaScript | `js`, `node` | Node.js 18+ |
+| Python | `py`, `python3` | Python 3.8+ |
+| Ruby | `rb` | Ruby 2.6+ |
+| PHP | — | PHP 7.4+ |
+| Go | `golang` | Go 1.18+ |
+| Rust | `rs`, `cargo` | Rust 1.70+ (fetches `serde_json`) |
+| C# | `cs`, `dotnet` | .NET 8 SDK |
+| Swift | — | Swift 5.5+ |
+
+Every language uses the same contract: implement `src/solution.<ext>`, read one
+JSON value from stdin, write one JSON value to stdout. The shared runner verifies
+any language identically.
+
+### Topic tags you can practice
+
+Any LeetCode topic tag works. Common ones and the kind of real-world scenario
+they tend to produce:
+
+| Tag | Typical generated domain |
+| --- | --- |
+| `array` | batch audit-log processor |
+| `string` | log sanitizer |
+| `hash-table` | event deduplication pipeline |
+| `two-pointers` | order-book matching engine |
+| `sliding-window` | API rate limiter |
+| `prefix-sum` | rolling revenue aggregator |
+| `binary-search` | price-threshold alert engine |
+| `sorting` | leaderboard ranker |
+| `heap-priority-queue` | background job scheduler |
+| `monotonic-stack` | histogram-based capacity planner |
+| `stack` | config-rule expression evaluator |
+| `queue` | async task pipeline |
+| `greedy` | resource bin-packing scheduler |
+| `dynamic-programming` | delivery route cost optimizer |
+| `graph` | microservice dependency resolver |
+| `depth-first-search` | permission inheritance resolver |
+| `breadth-first-search` | service-mesh shortest-path router |
+| `union-find` | account clustering for fraud rings |
+| `topological-sort` | build-order planner |
+| `trie` | autocomplete search index |
+| `tree` | filesystem index builder |
+| `linked-list` | LRU eviction chain |
+| `backtracking` | deployment permutation explorer |
+| `bit-manipulation` | feature-flag bitmask service |
+| `segment-tree` | range-quota enforcement service |
+| `design` | in-memory key-value store |
+| `database` | analytics reconciliation job |
+| `simulation` | tick-based match engine |
+
 ## How it works
 
 ```
@@ -35,13 +120,21 @@ The generated project looks like this:
 .practice/<project>/
 ├── README.md                 # quickstart + how to run
 ├── PROJECT.md                # scenario, requirements, definition of done
-├── package.json / tsconfig   # or requirements.txt for Python
-├── src/<module>.ts           # implement this
-├── tests/public/*            # visible behavioural tests
-├── tests/hidden/*            # extra acceptance tests (gitignored, guarded)
+├── harness.json              # build + run commands for the chosen language
+├── src/solution.<ext>        # implement this (one JSON in, one JSON out)
+├── tests/runner.mjs          # language-agnostic test harness (Node)
+├── tests/public/cases.json   # visible test cases
+├── tests/hidden/cases.json   # extra acceptance cases (gitignored, guarded)
 └── .practice-meta.json       # provenance only (gitignored, guarded)
 ```
 
+Run the checks with:
+
+```bash
+node tests/runner.mjs            # all cases
+node tests/runner.mjs --public   # visible cases only
+```
+
 ## Install
 
 ### Local (development)
@@ -66,7 +159,7 @@ The plugin registers the `/practice` command itself, so no extra config is neede
 | Tool | Purpose |
 | --- | --- |
 | `leetcode_fetch` | Fetch a problem by `mode` (`random` \| `specific` \| `daily` \| `filter`), `difficulty`, `tags`, `idOrSlug`. Skips premium problems. |
-| `leetcode_scaffold` | Create the real-world project from a spec. Rejects specs that mention LeetCode, the source title, or its slug. |
+| `leetcode_scaffold` | Create the real-world project from a spec in any supported language. Rejects specs that mention LeetCode, the source title, or its slug. |
 
 ## The honest-practice guard
 
@@ -106,8 +199,9 @@ command are resolved.
 src/
   index.ts      plugin entry: tools, guard hooks, command registration
   leetcode.ts   API client + normalizer (handles endpoint shape differences)
+  languages.ts  per-language adapters: starter, build, run commands
   patterns.ts   topic -> domain seeds, leak detection
-  scaffold.ts   deterministic project writer (TS/JS/Python)
+  scaffold.ts   deterministic project writer (any supported language)
   guard.ts      protected-path detection
   prompt.ts     the /practice command template
   types.ts      shared types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-leetcode-realworld",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -75,11 +75,20 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
       projectName: tool.schema.string().optional().describe("kebab-case directory name"),
       difficulty: tool.schema.string().optional(),
       language: tool.schema
-        .enum(["typescript", "javascript", "python"])
+        .enum([
+          "typescript",
+          "javascript",
+          "python",
+          "ruby",
+          "php",
+          "go",
+          "rust",
+          "csharp",
+          "swift",
+        ])
         .default("typescript")
-        .describe("Target language"),
-      module: tool.schema.string().optional().describe("Base module/file name"),
-      functionName: tool.schema.string().optional().describe("Exported entry function name"),
+        .describe("Target language for the practice project"),
+      functionName: tool.schema.string().optional().describe("Entry function name (default: solve)"),
       requirements: tool.schema.array(tool.schema.string()).default([]).describe("Testable requirements"),
       edgeCases: tool.schema.array(tool.schema.string()).default([]),
       starterCode: tool.schema.string().optional().describe("Optional starter implementation"),
@@ -117,7 +126,7 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
         `Created a real-world practice project at ${relative}`,
         "",
         `Title: ${result.title}`,
-        `Language: ${result.language}`,
+        `Language: ${result.languageName} (${result.runtime})`,
         `Files (${result.files.length}):`,
         ...result.files.map((file) => `  - ${file}`),
         "",

package/src/languages.ts

@@ -0,0 +1,358 @@
+import type { FileEntry, LanguageId } from "./types";
+
+export interface LanguageContext {
+  projectName: string;
+  functionName: string;
+  title: string;
+}
+
+export interface LanguageAdapter {
+  id: LanguageId;
+  name: string;
+  aliases: string[];
+  extension: string;
+  /** Human hint shown in the generated README. */
+  runtime: string;
+  starter(ctx: LanguageContext): string;
+  /** Extra project files (build manifests etc). */
+  files(ctx: LanguageContext): FileEntry[];
+  /** Command run once before the cases, or null when not needed. */
+  build(ctx: LanguageContext): string | null;
+  /** Command that runs the solution once, reading one JSON value on stdin. */
+  run(ctx: LanguageContext): string;
+}
+
+function packageJson(projectName: string, script: string): FileEntry {
+  return {
+    relative: "package.json",
+    contents:
+      JSON.stringify(
+        {
+          name: projectName,
+          version: "0.1.0",
+          private: true,
+          type: "module",
+          scripts: { test: script, check: script },
+        },
+        null,
+        2,
+      ) + "\n",
+  };
+}
+
+const adapters: Record<LanguageId, LanguageAdapter> = {
+  typescript: {
+    id: "typescript",
+    name: "TypeScript",
+    aliases: ["ts"],
+    extension: "ts",
+    runtime: "Node.js 22.6+ (uses `--experimental-strip-types`)",
+    starter: ({ functionName }) => `import { readFileSync } from "node:fs";
+
+function ${functionName}(payload: unknown): unknown {
+  throw new Error("Not implemented: ${functionName}");
+}
+
+const input = readFileSync(0, "utf8");
+const payload = JSON.parse(input.trim() === "" ? "null" : input);
+process.stdout.write(JSON.stringify(${functionName}(payload) ?? null));
+`,
+    files: (ctx) => [
+      packageJson(ctx.projectName, "node tests/runner.mjs"),
+      {
+        relative: "tsconfig.json",
+        contents:
+          JSON.stringify(
+            {
+              compilerOptions: {
+                target: "ES2022",
+                module: "ESNext",
+                moduleResolution: "bundler",
+                strict: true,
+                skipLibCheck: true,
+                types: ["node"],
+                noEmit: true,
+              },
+              include: ["src"],
+            },
+            null,
+            2,
+          ) + "\n",
+      },
+    ],
+    build: () => null,
+    run: ({ functionName }) => `node --experimental-strip-types src/solution.ts`,
+  },
+
+  javascript: {
+    id: "javascript",
+    name: "JavaScript",
+    aliases: ["js", "node"],
+    extension: "mjs",
+    runtime: "Node.js 18+",
+    starter: ({ functionName }) => `function ${functionName}(payload) {
+  throw new Error("Not implemented: ${functionName}");
+}
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+const input = Buffer.concat(chunks).toString("utf8");
+const payload = JSON.parse(input.trim() === "" ? "null" : input);
+process.stdout.write(JSON.stringify(${functionName}(payload) ?? null));
+`,
+    files: (ctx) => [packageJson(ctx.projectName, "node tests/runner.mjs")],
+    build: () => null,
+    run: () => "node src/solution.mjs",
+  },
+
+  python: {
+    id: "python",
+    name: "Python",
+    aliases: ["py", "python3"],
+    extension: "py",
+    runtime: "Python 3.8+",
+    starter: ({ functionName }) => `import json
+import sys
+
+
+def ${functionName}(payload):
+    raise NotImplementedError("Not implemented: ${functionName}")
+
+
+def main():
+    raw = sys.stdin.read().strip()
+    payload = json.loads(raw) if raw else None
+    print(json.dumps(${functionName}(payload)))
+
+
+if __name__ == "__main__":
+    main()
+`,
+    files: () => [],
+    build: () => null,
+    run: () => "python3 src/solution.py",
+  },
+
+  ruby: {
+    id: "ruby",
+    name: "Ruby",
+    aliases: ["rb"],
+    extension: "rb",
+    runtime: "Ruby 2.6+ (json is in the standard library)",
+    starter: ({ functionName }) => `require "json"
+
+def ${functionName}(payload)
+  raise NotImplementedError, "Not implemented: ${functionName}"
+end
+
+raw = $stdin.read.strip
+payload = raw.empty? ? nil : JSON.parse(raw)
+puts JSON.generate(${functionName}(payload))
+`,
+    files: () => [],
+    build: () => null,
+    run: () => "ruby src/solution.rb",
+  },
+
+  php: {
+    id: "php",
+    name: "PHP",
+    aliases: ["php8"],
+    extension: "php",
+    runtime: "PHP 7.4+",
+    starter: ({ functionName }) => `<?php
+
+function ${functionName}($payload) {
+    throw new Exception("Not implemented: ${functionName}");
+}
+
+$raw = trim(stream_get_contents(STDIN));
+$payload = $raw === "" ? null : json_decode($raw, true);
+echo json_encode(${functionName}($payload));
+`,
+    files: () => [],
+    build: () => null,
+    run: () => "php src/solution.php",
+  },
+
+  go: {
+    id: "go",
+    name: "Go",
+    aliases: ["golang"],
+    extension: "go",
+    runtime: "Go 1.18+ (uses `any`)",
+    starter: ({ functionName }) => `package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+)
+
+func ${functionName}(payload any) any {
+	panic("Not implemented: ${functionName}")
+}
+
+func main() {
+	raw, _ := io.ReadAll(os.Stdin)
+	var payload any
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &payload); err != nil {
+			panic(err)
+		}
+	}
+	out, err := json.Marshal(${functionName}(payload))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(string(out))
+}
+`,
+    files: () => [
+      { relative: "go.mod", contents: "module practice\n\ngo 1.21\n" },
+    ],
+    build: () => "mkdir -p out && go build -o out/solution src/solution.go",
+    run: () => "./out/solution",
+  },
+
+  rust: {
+    id: "rust",
+    name: "Rust",
+    aliases: ["rs", "cargo"],
+    extension: "rs",
+    runtime: "Rust 1.70+ (uses serde_json)",
+    starter: ({ functionName }) => `use serde_json::Value;
+use std::io::Read;
+
+fn ${functionName}(payload: Value) -> Value {
+    let _ = payload;
+    panic!("Not implemented: ${functionName}");
+}
+
+fn main() {
+    let mut raw = String::new();
+    std::io::stdin().read_to_string(&mut raw).expect("read stdin");
+    let trimmed = raw.trim();
+    let payload: Value = if trimmed.is_empty() {
+        Value::Null
+    } else {
+        serde_json::from_str(trimmed).expect("parse json")
+    };
+    let result = ${functionName}(payload);
+    println!("{}", serde_json::to_string(&result).expect("serialize json"));
+}
+`,
+    files: (ctx) => [
+      {
+        relative: "Cargo.toml",
+        contents: `[package]
+name = "${ctx.projectName}"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde_json = "1"
+
+[[bin]]
+name = "solution"
+path = "src/solution.rs"
+`,
+      },
+    ],
+    build: () => "cargo build --quiet",
+    run: () => "./target/debug/solution",
+  },
+
+  csharp: {
+    id: "csharp",
+    name: "C#",
+    aliases: ["cs", "dotnet"],
+    extension: "cs",
+    runtime: ".NET 8 SDK",
+    starter: ({ functionName }) => `using System;
+using System.Text.Json.Nodes;
+
+class Program
+{
+    static JsonNode? ${functionName}(JsonNode? payload)
+    {
+        throw new NotImplementedException("Not implemented: ${functionName}");
+    }
+
+    static void Main()
+    {
+        var raw = Console.In.ReadToEnd().Trim();
+        var payload = raw.Length == 0 ? null : JsonNode.Parse(raw);
+        Console.Write(${functionName}(payload)?.ToJsonString() ?? "null");
+    }
+}
+`,
+    files: (ctx) => [
+      {
+        relative: `${ctx.projectName}.csproj`,
+        contents: `<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>solution</AssemblyName>
+  </PropertyGroup>
+</Project>
+`,
+      },
+    ],
+    build: () => "dotnet build -c Release -o out --nologo -v quiet",
+    run: () => "dotnet out/solution.dll",
+  },
+
+  swift: {
+    id: "swift",
+    name: "Swift",
+    aliases: [],
+    extension: "swift",
+    runtime: "Swift 5.5+ (Foundation JSONSerialization)",
+    starter: ({ functionName }) => `import Foundation
+
+func ${functionName}(_ payload: Any) -> Any {
+    fatalError("Not implemented: ${functionName}")
+}
+
+let raw = String(data: FileHandle.standardInput.readDataToEndOfFile(), encoding: .utf8) ?? ""
+let data = raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    ? Data("null".utf8)
+    : Data(raw.utf8)
+let payload = try! JSONSerialization.jsonObject(with: data, options: [.fragmentsAllowed])
+let result = ${functionName}(payload)
+let out = try! JSONSerialization.data(withJSONObject: result, options: [.fragmentsAllowed])
+FileHandle.standardOutput.write(out)
+`,
+    files: () => [],
+    build: () => "mkdir -p out && swiftc -O src/solution.swift -o out/solution",
+    run: () => "./out/solution",
+  },
+};
+
+export function getLanguage(id: LanguageId): LanguageAdapter {
+  return adapters[id];
+}
+
+export function languageIds(): LanguageId[] {
+  return Object.keys(adapters) as LanguageId[];
+}
+
+export function languageNames(): string {
+  return languageIds()
+    .map((id) => adapters[id].name)
+    .join(", ");
+}
+
+export function normalizeLanguage(input: string | undefined): LanguageId | undefined {
+  if (!input) return undefined;
+  const key = input.trim().toLowerCase();
+  for (const adapter of Object.values(adapters)) {
+    if (adapter.id === key || adapter.aliases.includes(key)) return adapter.id;
+  }
+  return undefined;
+}

package/src/patterns.ts

@@ -91,7 +91,6 @@ function textsFromSpec(spec: ScaffoldSpec): Array<[string, string]> {
   push("projectName", spec.projectName);
   push("scenario", spec.scenario);
   push("pattern", spec.pattern);
-  push("module", spec.module);
   push("functionName", spec.functionName);
   push("starterCode", spec.starterCode);
   (spec.requirements ?? []).forEach((req, i) => push(`requirements[${i}]`, req));

package/src/prompt.ts

@@ -1,6 +1,18 @@
 export const PRACTICE_DESCRIPTION =
   "Turn a LeetCode problem into a realistic software-engineering assignment (scenario, starter, tests) so you practice applying the underlying algorithm, not solving the puzzle.";
 
+export const SUPPORTED_LANGUAGES = [
+  "TypeScript",
+  "JavaScript",
+  "Python",
+  "Ruby",
+  "PHP",
+  "Go",
+  "Rust",
+  "C#",
+  "Swift",
+];
+
 /**
  * The `/practice` command prompt. It orchestrates the two plugin tools and is
  * deliberately opinionated: the whole value of this plugin is that the learner
@@ -19,58 +31,77 @@ Recognise any of these (all optional):
 - difficulty: easy | medium | hard
 - tags: comma-separated topic tags, e.g. "dynamic-programming,graph"
 - a specific problem id or slug, e.g. "two-sum" or "1"
-- language: ts | js | python (default ts)
-If nothing is provided, pick a random Medium problem.
+- language: a supported language name or alias (below)
+
+## 2. Ask when unclear (use the \`question\` tool)
+Supported languages: ${SUPPORTED_LANGUAGES.join(", ")}.
+
+- 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.
 
-## 2. Fetch the source problem (private)
-Call the \`leetcode_fetch\` tool with the parsed options. The fetched statement is
-for YOUR reasoning only. Never paste it, paraphrase it closely, or name its source
-anywhere in the generated project.
+If the user did specify values, skip the corresponding question. Only ask at all
+when something is missing.
 
-## 3. Derive the principle
+## 3. Fetch the source problem (private)
+Call the \`leetcode_fetch\` tool with the difficulty/tags/slug. The fetched
+statement is for YOUR reasoning only. Never paste it, paraphrase it closely, or
+name its source anywhere in the generated project.
+
+## 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.).
 
-## 4. Invent a real engineering scenario
+## 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. Pick ONE clean entry point.
+"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.
 
-Design the assignment so a single exported function is the contract:
-- It receives one JSON-shaped \`payload\` value.
-- It returns one JSON-shaped result.
 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: chosen language
+- 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
 - starterCode: optional; otherwise a TODO stub is generated
-- publicTests: 3-5 visible cases that illustrate the contract
-- hiddenTests: 5-8 acceptance cases, including edge cases and one larger input
-- sourceSlug / sourceTitle: for internal provenance ONLY (never surfaced to the learner)
+- 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.
 
-## 5. Rules (non-negotiable)
+## 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 \`src/...\` themselves.
+  learner implements the solution file themselves.
 - Do not reveal the fetched problem or the original examples.
 - If the tool reports a leak, rewrite the offending fields and retry.
 
-## 6. After scaffolding
+## 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 reported by the tool.
-3. The exact commands to install dependencies and run the tests.
-4. Note that \`tests/hidden\` holds extra acceptance tests they should not edit.
+2. The project path and chosen 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.
 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

@@ -1,7 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { getLanguage, normalizeLanguage } from "./languages";
 import { assertNoLeak } from "./patterns";
-import type { PracticeLanguage, ScaffoldResult, ScaffoldSpec, TestCase } from "./types";
+import type { FileEntry, LanguageId, ScaffoldResult, ScaffoldSpec, TestCase } from "./types";
 
 function kebab(input: string): string {
   return input
@@ -18,101 +19,157 @@ function camel(input: string): string {
     .join("");
 }
 
-function snake(input: string): string {
-  return kebab(input).replace(/-/g, "_");
-}
-
-function pascal(input: string): string {
-  const value = camel(input);
-  return value.charAt(0).toUpperCase() + value.slice(1);
-}
-
 interface ResolvedNames {
   projectName: string;
-  module: string;
   functionName: string;
   title: string;
 }
 
 function resolveNames(spec: ScaffoldSpec): ResolvedNames {
   const projectName = kebab(spec.projectName ?? spec.title) || "practice-project";
-  const module = kebab(spec.module ?? spec.title) || "core";
-  const language = spec.language ?? "typescript";
-  const rawFunction = spec.functionName ?? (camel(module) || "solve");
-  const functionName = language === "python" ? snake(rawFunction) : camel(rawFunction);
-  return { projectName, module, functionName, title: spec.title };
+  const functionName = spec.functionName?.trim() || "solve";
+  return { projectName, functionName, title: spec.title };
 }
 
 function json(value: unknown, indent = 2): string {
   return JSON.stringify(value, null, indent);
 }
 
-function toPythonLiteral(value: unknown, depth = 0): string {
-  const pad = "    ".repeat(depth + 1);
-  const closePad = "    ".repeat(depth);
-  if (value === null) return "None";
-  if (value === true) return "True";
-  if (value === false) return "False";
-  if (typeof value === "number" || typeof value === "string") return JSON.stringify(value);
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
-    const items = value.map((item) => `${pad}${toPythonLiteral(item, depth + 1)}`);
-    return `[\n${items.join(",\n")},\n${closePad}]`;
+const RUNNER = String.raw`#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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"));
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonical(value[key]);
+    return out;
   }
-  if (typeof value === "object") {
-    const entries = Object.entries(value as Record<string, unknown>);
-    if (entries.length === 0) return "{}";
-    const items = entries.map(
-      ([key, val]) => `${pad}${JSON.stringify(key)}: ${toPythonLiteral(val, depth + 1)}`,
-    );
-    return `{\n${items.join(",\n")},\n${closePad}}`;
+  return value;
+}
+
+function same(a, b) {
+  return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+
+function runCase(input) {
+  const result = spawnSync(harness.run, {
+    cwd: root,
+    shell: true,
+    encoding: "utf8",
+    input: JSON.stringify(input),
+    timeout: 30000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim().split("\n").slice(-6).join("\n");
+    throw new Error("process exited with code " + result.status + (detail ? "\n" + detail : ""));
   }
-  return "None";
+  const text = (result.stdout || "").trim();
+  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);
+  }
+}
+
+const onlyPublic = process.argv.includes("--public");
+const suites = onlyPublic ? ["public"] : ["public", "hidden"];
+let passed = 0;
+let failed = 0;
+
+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 = 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));
+      }
+    } catch (error) {
+      failed += 1;
+      console.log("  ERROR " + testCase.name);
+      for (const line of String(error.message).split("\n")) {
+        console.log("        " + line);
+      }
+    }
+  }
+}
+
+console.log("\n" + passed + " passed, " + failed + " failed");
+process.exit(failed === 0 ? 0 : 1);
+`;
+
 function requirementsSection(spec: ScaffoldSpec): string {
   const requirements = spec.requirements ?? [];
   if (requirements.length === 0) return "";
-  const lines = requirements.map((req, i) => `${i + 1}. ${req}`);
-  return `## Requirements\n\n${lines.join("\n")}\n`;
+  return `## Requirements\n\n${requirements.map((req, i) => `${i + 1}. ${req}`).join("\n")}\n`;
 }
 
 function edgeCaseSection(spec: ScaffoldSpec): string {
   const edgeCases = spec.edgeCases ?? [];
   if (edgeCases.length === 0) return "";
-  const lines = edgeCases.map((edge) => `- ${edge}`);
-  return `## Edge cases to handle\n\n${lines.join("\n")}\n`;
+  return `## Edge cases to handle\n\n${edgeCases.map((edge) => `- ${edge}`).join("\n")}\n`;
 }
 
-function readmeFor(names: ResolvedNames, language: PracticeLanguage): string {
-  const run = runCommands(language);
+function readmeFor(names: ResolvedNames, spec: ScaffoldSpec, language: LanguageId): string {
+  const adapter = getLanguage(language);
+  const source = `src/solution.${adapter.extension}`;
+  const publicCount = (spec.publicTests ?? []).length;
+  const hiddenCount = (spec.hiddenTests ?? []).length;
   return `# ${names.title}
 
 ${names.title} is a self-contained engineering exercise. Read \`PROJECT.md\` for the
-business context and requirements, implement the entry point in \`${sourcePath(names, language)}\`,
-and make the test suite pass.
+brief, implement the entry point in \`${source}\`, and make the test suite pass.
 
-## Getting started
+## Run the tests
 
 \`\`\`bash
-${run.install ? `${run.install}\n` : ""}${run.check}
+node tests/runner.mjs
 \`\`\`
 
+Requires ${adapter.runtime}.
+
+- \`node tests/runner.mjs --public\` runs only the visible cases.
+- Your program reads **one JSON value on stdin** and writes **one JSON value on
+  stdout**. The starter file shows the exact shape.
+
 ## Layout
 
 \`\`\`
-${sourcePath(names, language)}   # implement your solution here
-tests/public/                  # visible behavioural tests
-tests/hidden/                  # additional acceptance tests (do not edit)
+${source}                     # implement your solution here
+tests/public/cases.json        # ${publicCount} visible cases
+tests/hidden/cases.json        # ${hiddenCount} acceptance cases (do not edit)
+tests/runner.mjs               # test harness
+harness.json                   # build/run commands
 PROJECT.md                     # scenario, requirements, definition of done
 \`\`\`
 
-Implement until \`${run.check}\` is green. Prefer clarity over cleverness: the goal is
-production-quality code, not the shortest possible snippet.
+Prefer clarity over cleverness: the goal is production-quality code, not the
+shortest possible snippet.
 `;
 }
 
-function projectDoc(spec: ScaffoldSpec, names: ResolvedNames): string {
+function projectDoc(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
+  const adapter = getLanguage(language);
   return `# ${names.title}
 
 ## Scenario
@@ -121,252 +178,79 @@ ${spec.scenario.trim()}
 
 ${requirementsSection(spec)}
 ${edgeCaseSection(spec)}
-## Definition of done
-
-- The entry point is implemented and exported as documented.
-- The full test suite passes: \`check\` command in the README.
-- No external service calls are required; input arrives as a plain value and the result is returned.
-- Handle the edge cases above rather than only the happy path.
-`;
-}
-
-function starterFor(names: ResolvedNames, spec: ScaffoldSpec, language: PracticeLanguage): string {
-  if (spec.starterCode && spec.starterCode.trim().length > 0) return spec.starterCode.trimEnd() + "\n";
-  const summary = spec.scenario.trim().split(/\n/)[0] ?? "";
-  if (language === "python") {
-    return `"""${names.title}.
-
-${summary}
-"""
-
-
-def ${names.functionName}(payload):
-    """Implement the behaviour described in PROJECT.md."""
-    raise NotImplementedError("${names.functionName} is not implemented yet")
-`;
-  }
-  const doc = `/**\n * ${names.title}\n *\n * ${summary}\n */`;
-  if (language === "javascript") {
-    return `${doc}\nexport function ${names.functionName}(payload) {\n  throw new Error("${names.functionName} is not implemented yet");\n}\n`;
-  }
-  const signature = `export function ${names.functionName}(payload: unknown): unknown {`;
-  return `${doc}\n${signature}\n  throw new Error("${names.functionName} is not implemented yet");\n}\n`;
-}
-
-function testCasesArray(cases: TestCase[]): string {
-  return json(cases, 2);
-}
-
-function publicTestFor(
-  names: ResolvedNames,
-  spec: ScaffoldSpec,
-  language: PracticeLanguage,
-): string {
-  const cases = spec.publicTests ?? [];
-  return testFile(names, cases, language, "public");
-}
-
-function hiddenTestFor(
-  names: ResolvedNames,
-  spec: ScaffoldSpec,
-  language: PracticeLanguage,
-): string {
-  const cases = spec.hiddenTests ?? [];
-  return testFile(names, cases, language, "hidden");
-}
-
-function testFile(
-  names: ResolvedNames,
-  cases: TestCase[],
-  language: PracticeLanguage,
-  kind: "public" | "hidden",
-): string {
-  const title = `${names.title} (${kind} acceptance)`;
-  if (language === "python") {
-    return `import pytest
+## Interface
 
-from src.${names.module} import ${names.functionName}
+Implement \`src/solution.${adapter.extension}\`. Your program is invoked once per test
+case: it reads **one JSON value from stdin** and must write **one JSON value to
+stdout**. Nothing else may be printed to stdout (use stderr for debugging).
 
-CASES = ${toPythonLiteral(cases)}
-
-
-@pytest.mark.parametrize("case", CASES, ids=lambda case: case["name"])
-def test_${names.functionName}(case):
-    assert ${names.functionName}(case["input"]) == case["expected"]
-`;
-  }
-  const casesLiteral = testCasesArray(cases);
-  if (language === "javascript") {
-    return `import test from "node:test";
-import assert from "node:assert/strict";
-import { ${names.functionName} } from "../../src/${names.module}.js";
-
-// ${title}
-const cases = ${casesLiteral};
-
-for (const testCase of cases) {
-  test(testCase.name, () => {
-    assert.deepStrictEqual(${names.functionName}(testCase.input), testCase.expected);
-  });
-}
-`;
-  }
-  return `import { describe, expect, it } from "vitest";
-import { ${names.functionName} } from "../../src/${names.module}";
-
-// ${title}
-const cases: Array<{ name: string; input: unknown; expected: unknown }> = ${casesLiteral};
+## Definition of done
 
-describe(${JSON.stringify(names.title)}, () => {
-  for (const testCase of cases) {
-    it(testCase.name, () => {
-      expect(${names.functionName}(testCase.input)).toEqual(testCase.expected);
-    });
-  }
-});
+- The full test suite passes: \`node tests/runner.mjs\`.
+- Edge cases above are handled, not just the happy path.
+- No network or external services are required.
 `;
 }
 
-function sourcePath(names: ResolvedNames, language: PracticeLanguage): string {
-  const ext = language === "python" ? "py" : language === "javascript" ? "js" : "ts";
-  return `src/${names.module}.${ext}`;
-}
-
-interface RunCommands {
-  install: string;
-  check: string;
-  run: string;
-}
-
-function runCommands(language: PracticeLanguage): RunCommands {
-  if (language === "python") {
-    return {
-      install: "python -m pip install -r requirements.txt",
-      check: "python -m pytest -q",
-      run: "python -m pytest -q",
-    };
-  }
-  if (language === "javascript") {
-    return { install: "npm install", check: "node --test", run: "node --test" };
-  }
-  return { install: "npm install", check: "npm test", run: "npm test" };
-}
-
-function packageJsonFor(
-  names: ResolvedNames,
-  language: PracticeLanguage,
-): string {
-  if (language === "javascript") {
-    return (
-      json(
-        {
-          name: names.projectName,
-          version: "0.1.0",
-          private: true,
-          type: "module",
-          scripts: { test: "node --test", check: "node --test" },
-        },
-        2,
-      ) + "\n"
-    );
-  }
-  return (
-    json(
-      {
-        name: names.projectName,
-        version: "0.1.0",
-        private: true,
-        type: "module",
-        scripts: { test: "vitest run", check: "vitest run" },
-        devDependencies: { "@types/node": "^22.13.9", typescript: "^5.8.2", vitest: "^3.0.0" },
-      },
-      2,
-    ) + "\n"
-  );
-}
-
-function tsconfigFor(): string {
-  return (
-    json(
-      {
-        compilerOptions: {
-          target: "ES2022",
-          module: "ESNext",
-          moduleResolution: "bundler",
-          strict: true,
-          skipLibCheck: true,
-          types: ["node"],
-          noEmit: true,
-        },
-        include: ["src", "tests"],
-      },
-      2,
-    ) + "\n"
-  );
-}
-
-const PROJECT_GITIGNORE = `node_modules/
+const PROJECT_GITIGNORE = `# build artifacts
+out/
+target/
+bin/
+obj/
+node_modules/
 __pycache__/
+*.pyc
 .pytest_cache/
-.venv/
-venv/
-# Acceptance tests are meant to stay local; don't commit the oracle.
+
+# acceptance tests + provenance stay local
 tests/hidden/
 .practice-meta.json
 `;
 
-function metaFor(spec: ScaffoldSpec, names: ResolvedNames, language: PracticeLanguage): string {
+function metaFor(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
   return (
-    json(
-      {
-        title: names.title,
-        module: names.module,
-        functionName: names.functionName,
-        language,
-        pattern: spec.pattern,
-        difficulty: spec.difficulty ?? null,
-        source: {
-          slug: spec.sourceSlug ?? null,
-          title: spec.sourceTitle ?? null,
-        },
-        generatedAt: new Date().toISOString(),
-      },
-      2,
-    ) + "\n"
+    json({
+      title: names.title,
+      functionName: names.functionName,
+      language,
+      pattern: spec.pattern,
+      difficulty: spec.difficulty ?? null,
+      source: { slug: spec.sourceSlug ?? null, title: spec.sourceTitle ?? null },
+      generatedAt: new Date().toISOString(),
+    }) + "\n"
   );
 }
 
-interface FileEntry {
-  relative: string;
-  contents: string;
+function casesFile(cases: TestCase[]): string {
+  return json(cases) + "\n";
 }
 
-function buildFiles(spec: ScaffoldSpec, names: ResolvedNames): FileEntry[] {
-  const language = spec.language ?? "typescript";
+function buildFiles(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): FileEntry[] {
+  const adapter = getLanguage(language);
+  const ctx = { projectName: names.projectName, functionName: names.functionName, title: names.title };
+
   const files: FileEntry[] = [
-    { relative: "README.md", contents: readmeFor(names, language) },
-    { relative: "PROJECT.md", contents: projectDoc(spec, names) },
+    { relative: "README.md", contents: readmeFor(names, spec, language) },
+    { relative: "PROJECT.md", contents: projectDoc(spec, names, language) },
     { relative: ".gitignore", contents: PROJECT_GITIGNORE },
     { relative: ".practice-meta.json", contents: metaFor(spec, names, language) },
-    { relative: sourcePath(names, language), contents: starterFor(names, spec, language) },
-    { relative: `tests/public/${names.module}.test.${language === "python" ? "py" : language === "javascript" ? "js" : "ts"}`, contents: publicTestFor(names, spec, language) },
-    { relative: `tests/hidden/${names.module}.test.${language === "python" ? "py" : language === "javascript" ? "js" : "ts"}`, contents: hiddenTestFor(names, spec, language) },
+    {
+      relative: "harness.json",
+      contents:
+        json({ build: adapter.build(ctx), run: adapter.run(ctx) }) + "\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 ?? []) },
+    {
+      relative: `src/solution.${adapter.extension}`,
+      contents: spec.starterCode?.trimEnd()
+        ? spec.starterCode.trimEnd() + "\n"
+        : adapter.starter(ctx),
+    },
   ];
 
-  if (language === "python") {
-    files.push(
-      { relative: "requirements.txt", contents: "pytest>=8.0\n" },
-      { relative: "conftest.py", contents: "import sys\nfrom pathlib import Path\n\nsys.path.insert(0, str(Path(__file__).parent))\n" },
-      { relative: "src/__init__.py", contents: "" },
-      { relative: "tests/__init__.py", contents: "" },
-      { relative: "tests/public/__init__.py", contents: "" },
-      { relative: "tests/hidden/__init__.py", contents: "" },
-    );
-  } else {
-    files.push({ relative: "package.json", contents: packageJsonFor(names, language) });
-    if (language === "typescript") files.push({ relative: "tsconfig.json", contents: tsconfigFor() });
-  }
-
+  files.push(...adapter.files(ctx));
   return files;
 }
 
@@ -379,7 +263,13 @@ export async function scaffold(
   spec: ScaffoldSpec,
   options: ScaffoldOptions,
 ): Promise<ScaffoldResult> {
-  const language = spec.language ?? "typescript";
+  const language = normalizeLanguage(spec.language) ?? (spec.language ? undefined : "typescript");
+  if (!language) {
+    throw new Error(
+      `Unsupported language "${spec.language}". Supported: typescript, javascript, python, ruby, php, go, rust, csharp, swift.`,
+    );
+  }
+
   const normalized: ScaffoldSpec = {
     ...spec,
     language,
@@ -391,27 +281,30 @@ export async function scaffold(
 
   assertNoLeak(normalized);
 
+  const adapter = getLanguage(language);
   const names = resolveNames(normalized);
   const target = normalized.outDir
     ? path.resolve(options.directory, normalized.outDir)
     : path.resolve(options.directory, ".practice", names.projectName);
 
-  const files = buildFiles(normalized, names);
+  const files = buildFiles(normalized, names, language);
   for (const file of files) {
     const destination = path.join(target, file.relative);
     await mkdir(path.dirname(destination), { recursive: true });
     await writeFile(destination, file.contents, "utf8");
   }
 
-  const commands = runCommands(language);
+  const check = "node tests/runner.mjs";
   return {
     outDir: target,
     title: names.title,
     language,
+    languageName: adapter.name,
+    runtime: adapter.runtime,
     files: files.map((file) => file.relative).sort(),
-    runCommand: commands.run,
-    checkCommand: commands.check,
+    runCommand: check,
+    checkCommand: check,
   };
 }
 
-export { resolveNames, kebab, camel, snake, pascal };
+export { resolveNames, kebab, camel };

package/src/types.ts

@@ -1,4 +1,13 @@
-export type PracticeLanguage = "typescript" | "javascript" | "python";
+export type LanguageId =
+  | "typescript"
+  | "javascript"
+  | "python"
+  | "ruby"
+  | "php"
+  | "go"
+  | "rust"
+  | "csharp"
+  | "swift";
 
 export interface CodeSnippet {
   lang: string;
@@ -35,6 +44,11 @@ export interface TestCase {
   expected: unknown;
 }
 
+export interface FileEntry {
+  relative: string;
+  contents: string;
+}
+
 /**
  * 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`
@@ -50,10 +64,8 @@ export interface ScaffoldSpec {
   /** Underlying algorithmic principle, e.g. "sliding window". Internal only. */
   pattern: string;
   difficulty?: string;
-  language?: PracticeLanguage;
-  /** Base module/file name, e.g. "deduper". Derived from title when omitted. */
-  module?: string;
-  /** Exported entry function, e.g. "dedupe". Derived from module when omitted. */
+  language?: LanguageId;
+  /** Name of the entry function inside the solution file. Defaults to `solve`. */
   functionName?: string;
   requirements?: string[];
   edgeCases?: string[];
@@ -71,7 +83,9 @@ export interface ScaffoldSpec {
 export interface ScaffoldResult {
   outDir: string;
   title: string;
-  language: PracticeLanguage;
+  language: LanguageId;
+  languageName: string;
+  runtime: string;
   files: string[];
   runCommand: string;
   checkCommand: string;