opencode-leetcode-realworld 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# opencode-leetcode-realworld
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [opencode](https://opencode.ai) plugin that turns a LeetCode problem into a
+**realistic software-engineering assignment**.
+
+Solving the puzzle and shipping the principle are different skills. This plugin
+fetches a problem, extracts the *underlying algorithm*, and generates a project
+that actually needs that algorithm — a scenario, requirements, a starter stub,
+and a test suite. The original problem is never shown to you.
+
+```
+/practice                          # random Medium problem
+/practice hard graph              # difficulty + tags
+/practice two-sum                  # a specific problem
+/practice medium dynamic-programming python
+```
+
+## How it works
+
+```
+/practice
+   │
+   ├─ 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
+   │
+   └─ guard hooks         block reading hidden tests + provenance, keep the exercise honest
+```
+
+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)
+└── .practice-meta.json       # provenance only (gitignored, guarded)
+```
+
+## Install
+
+### Local (development)
+
+Clone/copy this repo, then open opencode inside it. Files under
+`.opencode/plugins/` and `.opencode/commands/` are auto-loaded.
+
+### From npm (once published)
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-leetcode-realworld"]
+}
+```
+
+The plugin registers the `/practice` command itself, so no extra config is needed.
+
+## Tools
+
+| 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. |
+
+## The honest-practice guard
+
+Two plugin hooks keep the exercise meaningful:
+
+- **Leak rejection** — `leetcode_scaffold` scans every learner-visible string for
+  the source title/slug and practice-site names (`leetcode`, `neetcode`, ...). If
+  found, it refuses and tells the agent to rewrite.
+- **Access block** — `tool.execute.before` blocks `read`/`write`/`edit`/`glob`/
+  `grep`/`bash` from touching `tests/hidden/**`, `.practice-meta.json`, and
+  `.practice/meta.json`. You implement against the visible spec; the oracle stays
+  out of reach.
+
+## Configuration
+
+| Env var | Default | Description |
+| --- | --- | --- |
+| `LEETCODE_API_BASE` | `https://leetcode-api-pied.vercel.app` | Base URL of the LeetCode API. |
+
+Data comes from the community [leetcode-api](https://github.com/noworneverev/leetcode-api)
+project. This plugin is not affiliated with LeetCode.
+
+## Development
+
+```bash
+bun install
+bun test          # unit + integration tests
+bun run typecheck # tsc --noEmit
+```
+
+Run `opencode debug config` inside the repo to confirm the plugin and `/practice`
+command are resolved.
+
+## Project layout
+
+```
+src/
+  index.ts      plugin entry: tools, guard hooks, command registration
+  leetcode.ts   API client + normalizer (handles endpoint shape differences)
+  patterns.ts   topic -> domain seeds, leak detection
+  scaffold.ts   deterministic project writer (TS/JS/Python)
+  guard.ts      protected-path detection
+  prompt.ts     the /practice command template
+  types.ts      shared types
+.opencode/      local wiring so this repo is usable immediately
+tests/          unit + integration tests
+```

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "opencode-leetcode-realworld",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "leetcode",
+    "practice",
+    "interview",
+    "algorithms"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  }
+}

package/src/guard.ts

@@ -0,0 +1,61 @@
+/**
+ * The generated oracle tests and provenance file are the only things keeping the
+ * practice exercise honest. If the learner (or a helpful agent) can just read the
+ * hidden tests or the `.practice-meta.json` that points back to the original
+ * problem, the exercise collapses into "solve the LeetCode problem".
+ *
+ * These helpers detect tool calls that would touch those files so the plugin can
+ * block them.
+ */
+
+const GUARDED_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "glob",
+  "grep",
+  "list",
+  "find",
+  "bash",
+]);
+
+const HIDDEN_SEGMENT = /(^|[\/\s"'])tests\/hidden(\/|[\s"']|$)/;
+const META_FILE = /(^|[\/\s"'])\.practice-meta\.json/;
+const LEGACY_META = /(^|[\/\s"'])\.practice\/meta\.json/;
+
+export function normalizeReference(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+export function isProtectedReference(value: string): boolean {
+  const normalized = normalizeReference(value);
+  return HIDDEN_SEGMENT.test(normalized) || META_FILE.test(normalized) || LEGACY_META.test(normalized);
+}
+
+export function isGuardedTool(toolName: string): boolean {
+  return GUARDED_TOOLS.has(toolName);
+}
+
+/**
+ * Pull the path-like arguments out of a tool call. Deliberately conservative:
+ * we only inspect fields that name a file, directory, or shell command, so we
+ * never false-positive on prose or search patterns.
+ */
+export function collectPathReferences(toolName: string, args: Record<string, unknown>): string[] {
+  const references: string[] = [];
+  const add = (value: unknown) => {
+    if (typeof value === "string" && value.length > 0) references.push(value);
+  };
+
+  add(args.filePath);
+  add(args.path);
+  add(args.pattern);
+  add(args.command);
+  add(args.include);
+
+  if (toolName === "bash" && typeof args.command === "string") {
+    references.push(args.command);
+  }
+
+  return references;
+}

package/src/index.ts

@@ -0,0 +1,164 @@
+import path from "node:path";
+import { type Plugin, tool } from "@opencode-ai/plugin";
+import { collectPathReferences, isGuardedTool, isProtectedReference } from "./guard";
+import { fetchProblem, renderProblemForAgent } from "./leetcode";
+import { PRACTICE_DESCRIPTION, PRACTICE_TEMPLATE } from "./prompt";
+import { scaffold } from "./scaffold";
+import type { ScaffoldSpec } from "./types";
+
+const testCaseSchema = tool.schema.object({
+  name: tool.schema.string().describe("Short description of what the case asserts"),
+  input: tool.schema.any().describe("The single JSON-shaped payload passed to the entry function"),
+  expected: tool.schema.any().describe("The JSON-shaped value the entry function must return"),
+});
+
+export const LeetCodeRealWorld: Plugin = async ({ client, directory }) => {
+  const log = async (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    extra?: Record<string, unknown>,
+  ) => {
+    try {
+      await client.app.log({
+        body: { service: "leetcode-realworld", level, message, extra },
+      });
+    } catch {
+      /* logging must never break a session */
+    }
+  };
+
+  const fetchTool = tool({
+    description:
+      "Fetch a LeetCode problem (random, by id/slug, the daily challenge, or filtered by difficulty/tags). " +
+      "Use the returned algorithmic principle to design a real-world assignment. Never surface the raw problem to the learner.",
+    args: {
+      mode: tool.schema
+        .enum(["random", "specific", "daily", "filter"])
+        .default("random")
+        .describe("How to choose the problem"),
+      idOrSlug: tool.schema.string().optional().describe("Problem id or slug (required for mode=specific)"),
+      difficulty: tool.schema.enum(["Easy", "Medium", "Hard"]).optional(),
+      tags: tool.schema.array(tool.schema.string()).optional().describe("Topic tags, e.g. ['graph']"),
+    },
+    async execute(args, context) {
+      const problem = await fetchProblem({
+        mode: args.mode,
+        idOrSlug: args.idOrSlug,
+        difficulty: args.difficulty,
+        tags: args.tags,
+        signal: context.abort,
+      });
+      context.metadata({ title: `${problem.title} (${problem.difficulty})` });
+      await log("info", "Fetched problem", { slug: problem.slug, difficulty: problem.difficulty });
+      const metadata = {
+        id: problem.frontendId || problem.id,
+        slug: problem.slug,
+        title: problem.title,
+        difficulty: problem.difficulty,
+        topics: problem.topics,
+        url: problem.url,
+      };
+      return `${renderProblemForAgent(problem)}\n\n<!-- source-metadata ${JSON.stringify(
+        metadata,
+      )} -->`;
+    },
+  });
+
+  const scaffoldTool = tool({
+    description:
+      "Create a real-world practice project from a spec (scenario, requirements, starter, tests). " +
+      "Rejects any spec that leaks the original problem, its title, slug, or a coding-practice site name.",
+    args: {
+      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)"),
+      projectName: tool.schema.string().optional().describe("kebab-case directory name"),
+      difficulty: tool.schema.string().optional(),
+      language: tool.schema
+        .enum(["typescript", "javascript", "python"])
+        .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"),
+      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"),
+      publicTests: tool.schema.array(testCaseSchema).default([]).describe("Visible test cases"),
+      hiddenTests: tool.schema.array(testCaseSchema).default([]).describe("Extra acceptance test cases"),
+      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"),
+    },
+    async execute(rawArgs, context) {
+      const spec = rawArgs as ScaffoldSpec;
+      const result = await scaffold(spec, { directory: context.directory });
+      context.metadata({ title: result.title });
+
+      const relative = path.relative(context.directory, result.outDir) || ".";
+      await log("info", "Scaffolded practice project", {
+        outDir: relative,
+        language: result.language,
+        files: result.files.length,
+      });
+      try {
+        await client.tui.showToast({
+          body: {
+            title: "Practice project ready",
+            message: `${result.title} -> ${relative}`,
+            variant: "success",
+            duration: 5000,
+          },
+        });
+      } catch {
+        /* toast is best-effort */
+      }
+
+      return [
+        `Created a real-world practice project at ${relative}`,
+        "",
+        `Title: ${result.title}`,
+        `Language: ${result.language}`,
+        `Files (${result.files.length}):`,
+        ...result.files.map((file) => `  - ${file}`),
+        "",
+        `Check your work with: ${result.checkCommand}`,
+        "The solution is intentionally left unimplemented. Do not write it for the learner.",
+      ].join("\n");
+    },
+  });
+
+  return {
+    config: async (config) => {
+      const commands = (config.command ??= {});
+      if (!commands.practice) {
+        commands.practice = {
+          template: PRACTICE_TEMPLATE,
+          description: PRACTICE_DESCRIPTION,
+        };
+      }
+    },
+
+    tool: {
+      leetcode_fetch: fetchTool,
+      leetcode_scaffold: scaffoldTool,
+    },
+
+    "tool.execute.before": async (input, output) => {
+      if (!isGuardedTool(input.tool)) return;
+      const args = (output.args ?? {}) as Record<string, unknown>;
+      const reference = collectPathReferences(input.tool, args).find(isProtectedReference);
+      if (reference) {
+        throw new Error(
+          `[leetcode-realworld] "${reference}" is protected practice material and cannot be accessed. ` +
+            "Hidden acceptance tests and problem provenance are off-limits so the exercise stays honest.",
+        );
+      }
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        await log("debug", "Session idle", { cwd: directory });
+      }
+    },
+  };
+};

package/src/leetcode.ts

@@ -0,0 +1,257 @@
+import type { CodeSnippet, NormalizedProblem } from "./types";
+
+const DEFAULT_BASE_URL = "https://leetcode-api-pied.vercel.app";
+
+export function apiBaseUrl(): string {
+  return (process.env.LEETCODE_API_BASE ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+export interface FetchOptions {
+  /** How to choose the problem. Defaults to `random`. */
+  mode?: "random" | "specific" | "daily" | "filter";
+  /** Required when `mode` is `specific`. Accepts an id ("1") or a slug ("two-sum"). */
+  idOrSlug?: string;
+  difficulty?: "Easy" | "Medium" | "Hard";
+  tags?: string[];
+  signal?: AbortSignal;
+}
+
+async function getJson<T>(path: string, signal?: AbortSignal): Promise<T> {
+  const url = `${apiBaseUrl()}${path}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      signal,
+      headers: { accept: "application/json", "user-agent": "opencode-leetcode-realworld" },
+    });
+  } catch (error) {
+    throw new Error(`Failed to reach LeetCode API at ${url}: ${(error as Error).message}`);
+  }
+  if (!res.ok) {
+    throw new Error(`LeetCode API responded ${res.status} ${res.statusText} for ${url}`);
+  }
+  return (await res.json()) as T;
+}
+
+function htmlToText(html: string): string {
+  if (!html) return "";
+  return html
+    .replace(/<sup>\s*([^<]*)\s*<\/sup>/gi, "^$1")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|pre|li|ul|ol|h[1-6])>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function normalizeSnippets(raw: unknown): CodeSnippet[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((entry) => {
+      const record = entry as Record<string, unknown>;
+      return {
+        lang: String(record.lang ?? record.langSlug ?? ""),
+        langSlug: String(record.langSlug ?? record.langsSlug ?? record.lang ?? ""),
+        code: String(record.code ?? ""),
+      };
+    })
+    .filter((snippet) => snippet.code.length > 0);
+}
+
+function normalizeTopics(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((entry) => {
+      if (typeof entry === "string") return entry;
+      const record = entry as Record<string, unknown>;
+      return String(record.name ?? record.slug ?? "");
+    })
+    .filter((name) => name.length > 0);
+}
+
+function extractAcRate(raw: Record<string, unknown>): number | undefined {
+  if (typeof raw.acRate === "number") return raw.acRate;
+  if (typeof raw.stats === "string") {
+    try {
+      const parsed = JSON.parse(raw.stats) as { acRate?: string | number };
+      if (parsed.acRate !== undefined) return Number.parseFloat(String(parsed.acRate));
+    } catch {
+      /* ignore malformed stats */
+    }
+  }
+  return undefined;
+}
+
+export function normalizeProblem(
+  raw: Record<string, unknown>,
+  fallbackSlug?: string,
+): NormalizedProblem {
+  const nested = (raw.question ?? {}) as Record<string, unknown>;
+  const contentHtml = String(raw.content ?? nested.content ?? "");
+  const slug = String(
+    raw.titleSlug ?? raw.title_slug ?? raw.slug ?? nested.titleSlug ?? fallbackSlug ?? "",
+  );
+  const acRate = extractAcRate(raw);
+  return {
+    id: String(raw.questionId ?? nested.questionId ?? raw.id ?? ""),
+    frontendId: String(
+      raw.questionFrontendId ?? nested.questionFrontendId ?? raw.frontend_id ?? "",
+    ),
+    slug,
+    title: String(raw.title ?? nested.title ?? ""),
+    difficulty: String(raw.difficulty ?? nested.difficulty ?? "Unknown"),
+    url: String(raw.url ?? (slug ? `https://leetcode.com/problems/${slug}/` : "")),
+    topics: normalizeTopics(raw.topicTags ?? nested.topicTags),
+    contentHtml,
+    contentText: htmlToText(contentHtml),
+    hints: Array.isArray(raw.hints)
+      ? raw.hints.map((hint) => htmlToText(String(hint)))
+      : [],
+    snippets: normalizeSnippets(raw.codeSnippets ?? nested.codeSnippets),
+    acRate,
+    paidOnly: Boolean(raw.isPaidOnly ?? raw.paid_only ?? nested.isPaidOnly ?? false),
+    date: typeof raw.date === "string" ? raw.date : undefined,
+  };
+}
+
+function preferredSlug(idOrSlug: string | undefined): string | undefined {
+  if (!idOrSlug) return undefined;
+  return /^\d+$/.test(idOrSlug.trim()) ? undefined : idOrSlug.trim();
+}
+
+/**
+ * A problem is usable for practice generation only if it is free and actually
+ * carries a statement. The API returns `content: null` (with `isPaidOnly: true`)
+ * for premium problems.
+ */
+export function isUsableProblem(problem: NormalizedProblem): boolean {
+  return !problem.paidOnly && problem.contentText.trim().length > 40;
+}
+
+async function pickUsable(
+  make: () => Promise<NormalizedProblem>,
+  attempts = 6,
+): Promise<NormalizedProblem> {
+  let last: NormalizedProblem | undefined;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const candidate = await make();
+    last = candidate;
+    if (isUsableProblem(candidate)) return candidate;
+  }
+  if (!last) throw new Error("LeetCode API returned no problems.");
+  return last;
+}
+
+export async function getProblem(idOrSlug: string, signal?: AbortSignal): Promise<NormalizedProblem> {
+  const raw = await getJson<Record<string, unknown>>(
+    `/problem/${encodeURIComponent(idOrSlug)}`,
+    signal,
+  );
+  return normalizeProblem(raw, preferredSlug(idOrSlug));
+}
+
+interface RandomProblem {
+  title_slug?: string;
+  titleSlug?: string;
+}
+
+export async function getRandom(
+  opts: { difficulty?: string; tags?: string[]; signal?: AbortSignal } = {},
+): Promise<NormalizedProblem> {
+  const params = new URLSearchParams();
+  if (opts.difficulty) params.set("difficulty", opts.difficulty);
+  if (opts.tags?.length) params.set("tags", opts.tags.join(","));
+  const query = params.toString();
+  const raw = await getJson<RandomProblem>(`/random${query ? `?${query}` : ""}`, opts.signal);
+  const slug = raw.title_slug ?? raw.titleSlug;
+  if (!slug) throw new Error("LeetCode API /random did not return a problem slug.");
+  return getProblem(slug, opts.signal);
+}
+
+export async function getDaily(signal?: AbortSignal): Promise<NormalizedProblem> {
+  const raw = await getJson<Record<string, unknown>>("/daily", signal);
+  return normalizeProblem(raw);
+}
+
+interface FilterResponse {
+  problems?: Array<Record<string, unknown>>;
+}
+
+export async function getFiltered(
+  opts: { difficulty?: string; tags?: string[]; limit?: number; signal?: AbortSignal } = {},
+): Promise<NormalizedProblem> {
+  const params = new URLSearchParams();
+  if (opts.difficulty) params.set("difficulty", opts.difficulty);
+  if (opts.tags?.length) params.set("tags", opts.tags.join(","));
+  params.set("limit", String(opts.limit ?? 20));
+  const raw = await getJson<FilterResponse>(`/problems/filter?${params.toString()}`, opts.signal);
+  const candidates = raw.problems ?? [];
+  if (candidates.length === 0) throw new Error("LeetCode API returned no problems for the given filter.");
+  const choice = candidates[Math.floor(Math.random() * candidates.length)] as Record<string, unknown>;
+  const slug = String(choice.title_slug ?? choice.titleSlug ?? "");
+  if (!slug) throw new Error("Filtered problem is missing a slug.");
+  return getProblem(slug, opts.signal);
+}
+
+export async function fetchProblem(options: FetchOptions = {}): Promise<NormalizedProblem> {
+  const mode = options.mode ?? "random";
+  switch (mode) {
+    case "specific": {
+      if (!options.idOrSlug) throw new Error("`idOrSlug` is required when mode is `specific`.");
+      return getProblem(options.idOrSlug, options.signal);
+    }
+    case "daily": {
+      const daily = await getDaily(options.signal);
+      if (isUsableProblem(daily)) return daily;
+      return pickUsable(() =>
+        getRandom({ difficulty: options.difficulty, tags: options.tags, signal: options.signal }),
+      );
+    }
+    case "filter":
+      return pickUsable(() =>
+        getFiltered({
+          difficulty: options.difficulty,
+          tags: options.tags,
+          signal: options.signal,
+        }),
+      );
+    case "random":
+    default:
+      return pickUsable(() =>
+        getRandom({ difficulty: options.difficulty, tags: options.tags, signal: options.signal }),
+      );
+  }
+}
+
+export interface TagInfo {
+  name: string;
+  slug: string;
+  problem_count: number;
+}
+
+export async function getTags(signal?: AbortSignal): Promise<TagInfo[]> {
+  return getJson<TagInfo[]>("/tags", signal);
+}
+
+/** Render a compact, agent-friendly view of the problem. Never write this to disk. */
+export function renderProblemForAgent(problem: NormalizedProblem): string {
+  const lines: string[] = [];
+  lines.push(`# ${problem.title} (${problem.difficulty})`);
+  if (problem.topics.length) lines.push(`Topics: ${problem.topics.join(", ")}`);
+  if (problem.acRate !== undefined) lines.push(`Acceptance: ${problem.acRate}%`);
+  lines.push("");
+  lines.push(problem.contentText || "(no statement returned)");
+  if (problem.hints.length) {
+    lines.push("");
+    lines.push("## Hints (do not reveal verbatim)");
+    for (const hint of problem.hints) lines.push(`- ${hint}`);
+  }
+  return lines.join("\n");
+}

package/src/patterns.ts

@@ -0,0 +1,142 @@
+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("module", spec.module);
+  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,80 @@
+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.";
+
+/**
+ * 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: ts | js | python (default ts)
+If nothing is provided, pick a random Medium problem.
+
+## 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.
+
+## 3. 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
+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.
+
+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
+- 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)
+
+Test cases must be JSON-serialisable: \`{ "name": string, "input": any, "expected": any }\`.
+
+## 5. 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.
+- 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
+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.
+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,417 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { assertNoLeak } from "./patterns";
+import type { PracticeLanguage, 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("");
+}
+
+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 };
+}
+
+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}]`;
+  }
+  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 "None";
+}
+
+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`;
+}
+
+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`;
+}
+
+function readmeFor(names: ResolvedNames, language: PracticeLanguage): string {
+  const run = runCommands(language);
+  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.
+
+## Getting started
+
+\`\`\`bash
+${run.install ? `${run.install}\n` : ""}${run.check}
+\`\`\`
+
+## Layout
+
+\`\`\`
+${sourcePath(names, language)}   # implement your solution here
+tests/public/                  # visible behavioural tests
+tests/hidden/                  # additional acceptance tests (do not edit)
+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.
+`;
+}
+
+function projectDoc(spec: ScaffoldSpec, names: ResolvedNames): string {
+  return `# ${names.title}
+
+## Scenario
+
+${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
+
+from src.${names.module} import ${names.functionName}
+
+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};
+
+describe(${JSON.stringify(names.title)}, () => {
+  for (const testCase of cases) {
+    it(testCase.name, () => {
+      expect(${names.functionName}(testCase.input)).toEqual(testCase.expected);
+    });
+  }
+});
+`;
+}
+
+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/
+__pycache__/
+.pytest_cache/
+.venv/
+venv/
+# Acceptance tests are meant to stay local; don't commit the oracle.
+tests/hidden/
+.practice-meta.json
+`;
+
+function metaFor(spec: ScaffoldSpec, names: ResolvedNames, language: PracticeLanguage): 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"
+  );
+}
+
+interface FileEntry {
+  relative: string;
+  contents: string;
+}
+
+function buildFiles(spec: ScaffoldSpec, names: ResolvedNames): FileEntry[] {
+  const language = spec.language ?? "typescript";
+  const files: FileEntry[] = [
+    { relative: "README.md", contents: readmeFor(names, language) },
+    { relative: "PROJECT.md", contents: projectDoc(spec, names) },
+    { 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) },
+  ];
+
+  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() });
+  }
+
+  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 = spec.language ?? "typescript";
+  const normalized: ScaffoldSpec = {
+    ...spec,
+    language,
+    requirements: spec.requirements ?? [],
+    edgeCases: spec.edgeCases ?? [],
+    publicTests: spec.publicTests ?? [],
+    hiddenTests: spec.hiddenTests ?? [],
+  };
+
+  assertNoLeak(normalized);
+
+  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);
+  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);
+  return {
+    outDir: target,
+    title: names.title,
+    language,
+    files: files.map((file) => file.relative).sort(),
+    runCommand: commands.run,
+    checkCommand: commands.check,
+  };
+}
+
+export { resolveNames, kebab, camel, snake, pascal };

package/src/types.ts

@@ -0,0 +1,78 @@
+export type PracticeLanguage = "typescript" | "javascript" | "python";
+
+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;
+}
+
+/**
+ * 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?: 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. */
+  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: PracticeLanguage;
+  files: string[];
+  runCommand: string;
+  checkCommand: string;
+}