opencode-leetcode-realworld 0.2.3 → 0.4.0

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,9 @@ export const SUPPORTED_LANGUAGES = [
   "Swift",
 ];
 
+/** Languages that can receive a full multi-file project. */
+export const PROJECT_LANGUAGES = ["TypeScript", "Python", "Rust"];
+
 /**
  * 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,6 +35,7 @@ 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)
 
 Mapping rules:
 - A word that names a topic (array, string, graph, tree, dp/dynamic-programming,
@@ -42,77 +46,97 @@ Mapping rules:
 - 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.
 
-## 2. Ask when unclear (use the \`question\` tool)
-Supported languages: ${SUPPORTED_LANGUAGES.join(", ")}.
+## 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".
 
-- 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 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.
 
-If the user did specify values, skip the corresponding question. Only ask at all
-when something is missing.
+Wait for the 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.
+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.
 
 ## 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
+## 5. Build the assignment
 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")
+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.
+
+Both shapes:
 - requirements: concrete, testable bullet points
 - edgeCases: tricky situations the solution must handle
-- starterCode: optional; otherwise a TODO stub is generated
-- 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.
+- 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.
 
 ## 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 mode: leave the entry unimplemented;
+  project mode: leave the TODO unimplemented). The learner does that.
 - 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.
+2. The project path, mode, 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: which file/function holds 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

@@ -1,7 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { getLanguage, normalizeLanguage } from "./languages";
+import { getLanguage, normalizeLanguage, type LanguageContext } from "./languages";
 import { assertNoLeak } from "./patterns";
+import { schemaFromSamples } from "./schema";
 import type { FileEntry, LanguageId, ScaffoldResult, ScaffoldSpec, TestCase } from "./types";
 
 function kebab(input: string): string {
@@ -231,9 +232,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,
@@ -251,7 +258,17 @@ function casesFile(cases: TestCase[]): string {
 
 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 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: readmeFor(names, spec, language) },
@@ -278,6 +295,119 @@ 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 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.
+
+## 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
+
+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.
+
+## 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({ build: spec.buildCommand ?? adapter.build(ctx), run: spec.runCommand }) + "\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;
@@ -305,13 +435,35 @@ 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.runCommand) {
+      throw new Error("Project mode requires a `runCommand` (run one case, JSON on stdin/stdout).");
+    }
+  }
+
   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 });
@@ -325,6 +477,7 @@ export async function scaffold(
     language,
     languageName: adapter.name,
     runtime: adapter.runtime,
+    mode,
     files: files.map((file) => file.relative).sort(),
     runCommand: check,
     checkCommand: check,

package/src/schema.ts

@@ -0,0 +1,226 @@
+/**
+ * Infers a small structural schema from the sample test cases so the generated
+ * starter files can carry real types (type-safe languages) or a documented
+ * format (dynamic languages).
+ *
+ * This is intentionally schema-light: it only needs enough fidelity to describe
+ * JSON input/output shapes (objects, arrays, primitives, optionality).
+ */
+
+export type SchemaNode =
+  | { kind: "string" }
+  | { kind: "number"; integer: boolean }
+  | { kind: "boolean" }
+  | { kind: "null" }
+  | { kind: "unknown" }
+  | { kind: "array"; element: SchemaNode }
+  | { kind: "object"; fields: FieldSchema[] };
+
+export interface FieldSchema {
+  name: string;
+  schema: SchemaNode;
+  optional: boolean;
+}
+
+export function inferSchema(value: unknown): SchemaNode {
+  if (value === null || value === undefined) return { kind: "null" };
+  if (Array.isArray(value)) {
+    return { kind: "array", element: mergeMany(value.map(inferSchema)) };
+  }
+  switch (typeof value) {
+    case "string":
+      return { kind: "string" };
+    case "boolean":
+      return { kind: "boolean" };
+    case "number":
+      return { kind: "number", integer: Number.isInteger(value) };
+    case "object": {
+      const fields = Object.entries(value as Record<string, unknown>).map(([name, entry]) => ({
+        name,
+        schema: inferSchema(entry),
+        optional: false,
+      }));
+      return { kind: "object", fields };
+    }
+    default:
+      return { kind: "unknown" };
+  }
+}
+
+export function mergeSchemas(a: SchemaNode, b: SchemaNode): SchemaNode {
+  if (a.kind === "unknown") return b;
+  if (b.kind === "unknown") return a;
+  if (a.kind === "null") return b;
+  if (b.kind === "null") return a;
+
+  if (a.kind === "object" && b.kind === "object") {
+    const names = new Set([...a.fields.map((f) => f.name), ...b.fields.map((f) => f.name)]);
+    const fields: FieldSchema[] = [];
+    for (const name of names) {
+      const left = a.fields.find((f) => f.name === name);
+      const right = b.fields.find((f) => f.name === name);
+      if (left && right) {
+        fields.push({
+          name,
+          schema: mergeSchemas(left.schema, right.schema),
+          optional: left.optional && right.optional,
+        });
+      } else {
+        const only = (left ?? right)!;
+        fields.push({ name, schema: only.schema, optional: true });
+      }
+    }
+    return { kind: "object", fields };
+  }
+
+  if (a.kind === "array" && b.kind === "array") {
+    return { kind: "array", element: mergeSchemas(a.element, b.element) };
+  }
+
+  if (a.kind === "number" && b.kind === "number") {
+    return { kind: "number", integer: a.integer && b.integer };
+  }
+  if (a.kind === b.kind) return a;
+  return { kind: "unknown" };
+}
+
+function mergeMany(nodes: SchemaNode[]): SchemaNode {
+  if (nodes.length === 0) return { kind: "unknown" };
+  return nodes.reduce((acc, node) => mergeSchemas(acc, node));
+}
+
+export function schemaFromSamples(values: unknown[]): SchemaNode {
+  return mergeMany(values.map(inferSchema));
+}
+
+/** True when the schema contains only types representable as static types. */
+export function isFullyTyped(node: SchemaNode): boolean {
+  switch (node.kind) {
+    case "unknown":
+    case "null":
+      return false;
+    case "array":
+      return isFullyTyped(node.element);
+    case "object":
+      return node.fields.every((field) => isFullyTyped(field.schema));
+    default:
+      return true;
+  }
+}
+
+/** Human-readable signature, e.g. `{ amounts: number[]; target: number }`. */
+export function schemaSignature(node: SchemaNode): string {
+  switch (node.kind) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "unknown":
+      return "any";
+    case "array": {
+      const inner = schemaSignature(node.element);
+      return inner.includes(" ") ? `(${inner})[]` : `${inner}[]`;
+    }
+    case "object":
+      if (node.fields.length === 0) return "{}";
+      return `{ ${node.fields
+        .map((field) => `${field.name}${field.optional ? "?" : ""}: ${schemaSignature(field.schema)}`)
+        .join("; ")} }`;
+  }
+}
+
+export type TypeRef =
+  | { t: "string" }
+  | { t: "int" }
+  | { t: "double" }
+  | { t: "bool" }
+  | { t: "any" }
+  | { t: "null" }
+  | { t: "array"; of: TypeRef }
+  | { t: "named"; name: string };
+
+export interface TypeDecl {
+  name: string;
+  fields: { name: string; ref: TypeRef; optional: boolean }[];
+}
+
+export function buildTypes(
+  rootName: string,
+  node: SchemaNode,
+): { root: TypeRef; decls: TypeDecl[] } {
+  const decls: TypeDecl[] = [];
+  const root = refFor(rootName, node, decls);
+  return { root, decls };
+}
+
+function refFor(name: string, node: SchemaNode, decls: TypeDecl[]): TypeRef {
+  switch (node.kind) {
+    case "object": {
+      const decl: TypeDecl = { name, fields: [] };
+      decls.push(decl);
+      for (const field of node.fields) {
+        decl.fields.push({
+          name: field.name,
+          optional: field.optional,
+          ref: refFor(`${name}${pascal(field.name)}`, field.schema, decls),
+        });
+      }
+      return { t: "named", name };
+    }
+    case "array":
+      return { t: "array", of: refFor(`${name}Item`, node.element, decls) };
+    case "string":
+      return { t: "string" };
+    case "boolean":
+      return { t: "bool" };
+    case "null":
+      return { t: "null" };
+    case "unknown":
+      return { t: "any" };
+    case "number":
+      return { t: node.integer ? "int" : "double" };
+  }
+}
+
+export function pascal(input: string): string {
+  const parts = input
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean);
+  return parts.map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+
+export function snake(input: string): string {
+  const value = input
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+  return /^[0-9]/.test(value) ? `_${value}` : value || "field";
+}
+
+const RESERVED = new Set([
+  "abstract", "as", "async", "await", "base", "bool", "break", "byte", "case", "catch",
+  "class", "const", "continue", "crate", "default", "delegate", "do", "double", "dyn",
+  "else", "enum", "event", "explicit", "extern", "false", "final", "finally", "fixed",
+  "float", "fn", "for", "foreach", "func", "goto", "if", "impl", "implements", "import",
+  "in", "int", "interface", "internal", "is", "let", "lock", "long", "loop", "match",
+  "mod", "move", "mut", "namespace", "new", "null", "object", "operator", "out",
+  "override", "package", "params", "private", "protected", "pub", "public", "readonly",
+  "ref", "return", "self", "short", "sizeof", "static", "string", "struct", "super",
+  "switch", "this", "throw", "trait", "true", "try", "type", "typeof", "uint", "ulong",
+  "unchecked", "unsafe", "use", "ushort", "var", "virtual", "void", "volatile", "where",
+  "while", "with", "yield",
+]);
+
+export function isReserved(word: string): boolean {
+  return RESERVED.has(word.toLowerCase());
+}
+
+export function isIdentifier(word: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(word);
+}

package/src/types.ts

@@ -49,12 +49,22 @@ export interface FileEntry {
   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;
   /** 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 +79,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 +88,16 @@ 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;
+  /** Command that runs one test case (JSON on stdin, JSON on stdout). */
+  runCommand?: string;
+  /** Optional one-time build command (compiled languages). */
+  buildCommand?: string;
 }
 
 export interface ScaffoldResult {
@@ -86,6 +106,7 @@ export interface ScaffoldResult {
   language: LanguageId;
   languageName: string;
   runtime: string;
+  mode: PracticeMode;
   files: string[];
   runCommand: string;
   checkCommand: string;