opencode-leetcode-realworld 0.3.0 → 0.4.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,34 @@ 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, 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.
+
 The generated project looks like this:
 
 ```

package/package.json

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

@@ -71,9 +71,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 +108,22 @@ 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("Project mode: command that runs one case (JSON on stdin, JSON on stdout)"),
+      buildCommand: tool.schema
+        .string()
+        .optional()
+        .describe("Project mode: optional one-time build command (compiled languages)"),
     },
     async execute(rawArgs, context) {
       const spec = rawArgs as ScaffoldSpec;
@@ -131,6 +153,7 @@ export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
         `Created a real-world practice project at ${relative}`,
         "",
         `Title: ${result.title}`,
+        `Mode: ${result.mode}${result.mode === "project" ? " (implement the marked TODO)" : ""}`,
         `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,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,82 +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
-- 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.
+- 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

@@ -232,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,
@@ -289,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;
@@ -316,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 });
@@ -336,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/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;