opencode-leetcode-realworld 0.0.0-stage → 0.2.0

package/src/patterns.ts

@@ -0,0 +1,141 @@
+import type { ScaffoldSpec } from "./types";
+
+/**
+ * Deterministic fallback inspiration. Maps a normalized topic tag to plausible
+ * real-world domains that exercise the same underlying principle. The agent is
+ * free to invent better scenarios; this exists so a sensible seed is always
+ * available even with a weak model.
+ */
+export const DOMAIN_SEEDS: Record<string, string[]> = {
+  array: ["batch audit-log processor", "telemetry windowing service"],
+  string: ["log sanitizer", "template renderer"],
+  "hash-table": ["event deduplication pipeline", "feature-flag lookup cache"],
+  "two-pointers": ["order-book matching engine", "sorted log-stream merger"],
+  "sliding-window": ["API rate limiter", "rolling p95 latency tracker"],
+  "binary-search": ["price-threshold alert engine", "pagination cursor resolver"],
+  "binary-search-tree": ["in-memory index range scanner", "time-series retention policy"],
+  "heap-priority-queue": ["background job scheduler", "incident severity triage"],
+  "priority-queue": ["background job scheduler", "incident severity triage"],
+  "dynamic-programming": ["delivery route cost optimizer", "budget allocation planner"],
+  greedy: ["resource bin-packing scheduler", "ad-slot allocator"],
+  graph: ["microservice dependency resolver", "network topology mapper"],
+  "depth-first-search": ["permission inheritance resolver", "nested category walker"],
+  "breadth-first-search": ["service-mesh shortest-path router", "org-chart traversal"],
+  "union-find": ["account clustering for fraud rings", "network segment merger"],
+  trie: ["autocomplete search index", "routing prefix matcher"],
+  stack: ["config-rule expression evaluator", "undo/redo command stack"],
+  queue: ["async task pipeline", "event buffer"],
+  "monotonic-stack": ["stock-span style sidebar calculator", "histogram-based capacity planner"],
+  sorting: ["leaderboard ranker", "changelog assembly job"],
+  backtracking: ["deployment permutation explorer", "seat-assignment planner"],
+  "bit-manipulation": ["feature-flag bitmask service", "compact permission encoder"],
+  math: ["billing proration engine", "metrics aggregation service"],
+  design: ["in-memory key-value store", "rate-limited API gateway"],
+  "linked-list": ["LRU eviction chain", "streaming ring buffer"],
+  tree: ["filesystem index builder", "org hierarchy aggregator"],
+  "prefix-sum": ["rolling revenue aggregator", "subnet traffic accounting"],
+  "segment-tree": ["range-quota enforcement service", "metrics rollup store"],
+  database: ["analytics reconciliation job", "query result differ"],
+  simulation: ["tick-based match engine", "capacity planning simulator"],
+  "ordered-set": ["leaderboard with rank lookup", "scheduler keyed by priority"],
+  "topological-sort": ["build-order planner", "migration dependency sequencer"],
+};
+
+/** Tags that are too generic to drive a scenario on their own. */
+const WEAK_TAGS = new Set(["algorithms", "database", "math"]);
+
+function normalizeTag(tag: string): string {
+  return tag.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function domainSeedsFor(topics: string[]): string[] {
+  const seeds: string[] = [];
+  for (const topic of topics) {
+    const key = normalizeTag(topic);
+    const matches = DOMAIN_SEEDS[key];
+    if (matches && !WEAK_TAGS.has(key)) seeds.push(...matches);
+  }
+  if (seeds.length === 0) {
+    seeds.push("internal developer-tooling service", "operations workflow automation");
+  }
+  return Array.from(new Set(seeds));
+}
+
+export function pickDomainSeed(topics: string[], random: () => number = Math.random): string {
+  const seeds = domainSeedsFor(topics);
+  return seeds[Math.floor(random() * seeds.length)] ?? seeds[0]!;
+}
+
+const GENERIC_BANNED_TERMS = [
+  "leetcode",
+  "leet code",
+  "geeksforgeeks",
+  "hackerrank",
+  "codewars",
+  "neetcode",
+  "blind 75",
+  "grind 75",
+];
+
+export interface LeakReport {
+  term: string;
+  field: string;
+}
+
+function textsFromSpec(spec: ScaffoldSpec): Array<[string, string]> {
+  const entries: Array<[string, string]> = [];
+  const push = (field: string, value: unknown) => {
+    if (typeof value === "string" && value.length > 0) entries.push([field, value]);
+  };
+  push("title", spec.title);
+  push("projectName", spec.projectName);
+  push("scenario", spec.scenario);
+  push("pattern", spec.pattern);
+  push("functionName", spec.functionName);
+  push("starterCode", spec.starterCode);
+  (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));
+  return entries;
+}
+
+/**
+ * Guards the core promise of the plugin: the assignment must not be the LeetCode
+ * problem in disguise. Scans every learner-visible string for the source problem
+ * and generic problem-site branding.
+ */
+export function findLeaks(spec: ScaffoldSpec): LeakReport[] {
+  const lowered = spec.sourceTitle?.toLowerCase().trim();
+  const sourceSlug = spec.sourceSlug?.toLowerCase().trim();
+  const reports: LeakReport[] = [];
+
+  for (const [field, value] of textsFromSpec(spec)) {
+    const haystack = value.toLowerCase();
+    for (const term of GENERIC_BANNED_TERMS) {
+      if (haystack.includes(term)) reports.push({ term, field });
+    }
+    if (lowered && lowered.length > 3 && haystack.includes(lowered)) {
+      reports.push({ term: `source title "${spec.sourceTitle}"`, field });
+    }
+    if (sourceSlug && sourceSlug.length > 2 && haystack.includes(sourceSlug)) {
+      reports.push({ term: `source slug "${spec.sourceSlug}"`, field });
+    }
+  }
+
+  const unique = new Map<string, LeakReport>();
+  for (const report of reports) unique.set(`${report.term}::${report.field}`, report);
+  return Array.from(unique.values());
+}
+
+export function assertNoLeak(spec: ScaffoldSpec): void {
+  const leaks = findLeaks(spec);
+  if (leaks.length === 0) return;
+  const details = leaks.map((l) => `  - "${l.term}" in ${l.field}`).join("\n");
+  throw new Error(
+    "The scaffold spec leaks the original problem, which breaks the whole point of this plugin.\n" +
+      "Rewrite the flagged fields so the assignment stands on its own as real software work:\n" +
+      `${details}\n` +
+      "Never mention the problem title, its slug, or any coding-practice site.",
+  );
+}

package/src/prompt.ts

@@ -0,0 +1,111 @@
+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
+ * never sees the original puzzle.
+ */
+export const PRACTICE_TEMPLATE = `You are running the "LeetCode -> Real World" practice generator.
+
+Goal: fetch a LeetCode problem, extract the *algorithmic principle* behind it, and
+produce a realistic software-engineering assignment that requires the same
+principle. The learner must solve a genuine engineering task, never the original
+puzzle.
+
+## 1. Parse arguments
+Arguments: "$ARGUMENTS"
+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: 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.
+
+If the user did specify values, skip the corresponding question. Only ask at all
+when something is missing.
+
+## 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.).
+
+## 5. Invent a real engineering scenario
+Design a plausible product/business task that genuinely needs that principle. Good
+domains: observability pipelines, payments/ledgering, logistics, rate limiting,
+access control, search, feature flags, data reconciliation, scheduling.
+The scenario must read like a ticket from a real team: who needs it, why, and what
+"correct" means.
+
+The assignment has ONE entry point with a JSON-in / JSON-out contract:
+- It receives a single JSON value (usually an object describing a request).
+- It returns a single JSON value (a response or result).
+This is how real services, CLIs and jobs exchange data, and it lets the same test
+harness verify any language.
+
+Call the tool \`leetcode_scaffold\` with a spec containing:
+- title: real-world project title (no coding-practice words)
+- scenario: 1-3 paragraphs of business context
+- pattern: the underlying principle (internal only)
+- language: the language the user chose (use the canonical id, e.g. "typescript",
+  "javascript", "python", "ruby", "php", "go", "rust", "csharp", "swift")
+- requirements: concrete, testable bullet points
+- edgeCases: tricky situations the solution must handle
+- 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.
+
+## 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.
+- 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.
+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.
+`;
+
+export function practiceTemplate(): string {
+  return PRACTICE_TEMPLATE;
+}

package/src/scaffold.ts

@@ -0,0 +1,310 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getLanguage, normalizeLanguage } from "./languages";
+import { assertNoLeak } from "./patterns";
+import type { FileEntry, LanguageId, ScaffoldResult, ScaffoldSpec, TestCase } from "./types";
+
+function kebab(input: string): string {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function camel(input: string): string {
+  const parts = kebab(input).split("-").filter(Boolean);
+  return parts
+    .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join("");
+}
+
+interface ResolvedNames {
+  projectName: string;
+  functionName: string;
+  title: string;
+}
+
+function resolveNames(spec: ScaffoldSpec): ResolvedNames {
+  const projectName = kebab(spec.projectName ?? spec.title) || "practice-project";
+  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);
+}
+
+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;
+  }
+  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 : ""));
+  }
+  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 "";
+  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 "";
+  return `## Edge cases to handle\n\n${edgeCases.map((edge) => `- ${edge}`).join("\n")}\n`;
+}
+
+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
+brief, implement the entry point in \`${source}\`, and make the test suite pass.
+
+## Run the tests
+
+\`\`\`bash
+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
+
+\`\`\`
+${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
+\`\`\`
+
+Prefer clarity over cleverness: the goal is production-quality code, not the
+shortest possible snippet.
+`;
+}
+
+function projectDoc(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
+  const adapter = getLanguage(language);
+  return `# ${names.title}
+
+## Scenario
+
+${spec.scenario.trim()}
+
+${requirementsSection(spec)}
+${edgeCaseSection(spec)}
+## Interface
+
+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).
+
+## Definition of done
+
+- 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.
+`;
+}
+
+const PROJECT_GITIGNORE = `# build artifacts
+out/
+target/
+bin/
+obj/
+node_modules/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# acceptance tests + provenance stay local
+tests/hidden/
+.practice-meta.json
+`;
+
+function metaFor(spec: ScaffoldSpec, names: ResolvedNames, language: LanguageId): string {
+  return (
+    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"
+  );
+}
+
+function casesFile(cases: TestCase[]): string {
+  return json(cases) + "\n";
+}
+
+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, 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: "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),
+    },
+  ];
+
+  files.push(...adapter.files(ctx));
+  return files;
+}
+
+export interface ScaffoldOptions {
+  /** Base directory to resolve relative paths against (the session directory). */
+  directory: string;
+}
+
+export async function scaffold(
+  spec: ScaffoldSpec,
+  options: ScaffoldOptions,
+): Promise<ScaffoldResult> {
+  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,
+    requirements: spec.requirements ?? [],
+    edgeCases: spec.edgeCases ?? [],
+    publicTests: spec.publicTests ?? [],
+    hiddenTests: spec.hiddenTests ?? [],
+  };
+
+  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, 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 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: check,
+    checkCommand: check,
+  };
+}
+
+export { resolveNames, kebab, camel };

package/src/types.ts

@@ -0,0 +1,92 @@
+export type LanguageId =
+  | "typescript"
+  | "javascript"
+  | "python"
+  | "ruby"
+  | "php"
+  | "go"
+  | "rust"
+  | "csharp"
+  | "swift";
+
+export interface CodeSnippet {
+  lang: string;
+  langSlug: string;
+  code: string;
+}
+
+/**
+ * A LeetCode problem reduced to a stable, API-shape-agnostic structure.
+ * The upstream API is not perfectly consistent between endpoints, so everything
+ * is funneled through `normalizeProblem` before it reaches the rest of the plugin.
+ */
+export interface NormalizedProblem {
+  id: string;
+  frontendId: string;
+  slug: string;
+  title: string;
+  difficulty: string;
+  url: string;
+  topics: string[];
+  contentHtml: string;
+  contentText: string;
+  hints: string[];
+  snippets: CodeSnippet[];
+  acRate?: number;
+  paidOnly: boolean;
+  /** Only present for the `/daily` endpoint. */
+  date?: string;
+}
+
+export interface TestCase {
+  name: string;
+  input: unknown;
+  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`
+ * before writing anything to disk.
+ */
+export interface ScaffoldSpec {
+  /** kebab-case directory name. Derived from `title` when omitted. */
+  projectName?: string;
+  /** Human title of the *real-world* project, e.g. "Realtime Dedup Pipeline". */
+  title: string;
+  /** Business context. Explains why the project matters and what it must do. */
+  scenario: string;
+  /** Underlying algorithmic principle, e.g. "sliding window". Internal only. */
+  pattern: string;
+  difficulty?: string;
+  language?: LanguageId;
+  /** Name of the entry function inside the solution file. Defaults to `solve`. */
+  functionName?: string;
+  requirements?: string[];
+  edgeCases?: string[];
+  /** Optional starter implementation. A TODO stub is generated when omitted. */
+  starterCode?: string;
+  publicTests?: TestCase[];
+  hiddenTests?: TestCase[];
+  /** Directory to create the project in, relative to the session directory. */
+  outDir?: string;
+  /** Internal provenance, stored in `.practice-meta.json` only. Never leaked. */
+  sourceSlug?: string;
+  sourceTitle?: string;
+}
+
+export interface ScaffoldResult {
+  outDir: string;
+  title: string;
+  language: LanguageId;
+  languageName: string;
+  runtime: string;
+  files: string[];
+  runCommand: string;
+  checkCommand: string;
+}