opencode-leetcode-realworld 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,210 @@
-# 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
+```
+
+## Usage
+
+```
+/practice [options]
+```
+
+Options can be given in any order; the command figures out which is which.
+
+### Options
+
+| Option | Accepted values | Default | Description |
+| --- | --- | --- | --- |
+| `difficulty` | `easy` \| `medium` \| `hard` | **asks you** (Medium suggested) | Difficulty of the source problem. |
+| `tags` | One or more topic tags, comma-separated (e.g. `graph` or `dynamic-programming,sliding-window`) | any | Nudges which underlying algorithm and real-world domain you get. |
+| `<id-or-slug>` | A problem number or slug (e.g. `1`, `two-sum`) | random | Derive the assignment from one specific source problem. |
+| `language` | A supported language or alias (see below) | **asks you** | Language of the generated project and tests. |
+
+If you leave the language (or difficulty) out, opencode **asks you** with a
+multiple-choice question before generating anything.
+
+### Examples
+
+| Command | What you get |
+| --- | --- |
+| `/practice` | Asks for language + difficulty, then builds a random Medium problem. |
+| `/practice easy` | Asks for the language, then an Easy problem. |
+| `/practice hard graph` | Hard problem tagged Graph. |
+| `/practice two-sum` | Asks for the language, then builds from the Two Sum problem. |
+| `/practice medium dynamic-programming python` | Medium DP problem, Python project. |
+| `/practice sliding-window js` | Random sliding-window problem in JavaScript. |
+
+### Supported languages
+
+| Language | Aliases | Runtime needed |
+| --- | --- | --- |
+| TypeScript | `ts` | Node.js 22.6+ |
+| JavaScript | `js`, `node` | Node.js 18+ |
+| Python | `py`, `python3` | Python 3.8+ |
+| Ruby | `rb` | Ruby 2.6+ |
+| PHP | — | PHP 7.4+ |
+| Go | `golang` | Go 1.18+ |
+| Rust | `rs`, `cargo` | Rust 1.70+ (fetches `serde_json`) |
+| C# | `cs`, `dotnet` | .NET 8 SDK |
+| Swift | — | Swift 5.5+ |
+
+Every language uses the same contract: implement `src/solution.<ext>`, read one
+JSON value from stdin, write one JSON value to stdout. The shared runner verifies
+any language identically.
+
+### Topic tags you can practice
+
+Any LeetCode topic tag works. Common ones and the kind of real-world scenario
+they tend to produce:
+
+| Tag | Typical generated domain |
+| --- | --- |
+| `array` | batch audit-log processor |
+| `string` | log sanitizer |
+| `hash-table` | event deduplication pipeline |
+| `two-pointers` | order-book matching engine |
+| `sliding-window` | API rate limiter |
+| `prefix-sum` | rolling revenue aggregator |
+| `binary-search` | price-threshold alert engine |
+| `sorting` | leaderboard ranker |
+| `heap-priority-queue` | background job scheduler |
+| `monotonic-stack` | histogram-based capacity planner |
+| `stack` | config-rule expression evaluator |
+| `queue` | async task pipeline |
+| `greedy` | resource bin-packing scheduler |
+| `dynamic-programming` | delivery route cost optimizer |
+| `graph` | microservice dependency resolver |
+| `depth-first-search` | permission inheritance resolver |
+| `breadth-first-search` | service-mesh shortest-path router |
+| `union-find` | account clustering for fraud rings |
+| `topological-sort` | build-order planner |
+| `trie` | autocomplete search index |
+| `tree` | filesystem index builder |
+| `linked-list` | LRU eviction chain |
+| `backtracking` | deployment permutation explorer |
+| `bit-manipulation` | feature-flag bitmask service |
+| `segment-tree` | range-quota enforcement service |
+| `design` | in-memory key-value store |
+| `database` | analytics reconciliation job |
+| `simulation` | tick-based match engine |
+
+## How it works
+
+```
+/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
+├── harness.json              # build + run commands for the chosen language
+├── src/solution.<ext>        # implement this (one JSON in, one JSON out)
+├── tests/runner.mjs          # language-agnostic test harness (Node)
+├── tests/public/cases.json   # visible test cases
+├── tests/hidden/cases.json   # extra acceptance cases (gitignored, guarded)
+└── .practice-meta.json       # provenance only (gitignored, guarded)
+```
+
+Run the checks with:
+
+```bash
+node tests/runner.mjs            # all cases
+node tests/runner.mjs --public   # visible cases only
+```
+
+## Install
+
+### Local (development)
+
+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 in any supported language. 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)
+  languages.ts  per-language adapters: starter, build, run commands
+  patterns.ts   topic -> domain seeds, leak detection
+  scaffold.ts   deterministic project writer (any supported language)
+  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.2.0",
+  "description": "OpenCode plugin that turns a LeetCode problem into a realistic software-engineering assignment, so you practice applying the underlying algorithm instead of solving the puzzle.",
+  "type": "module",
+  "license": "MIT",
+  "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,173 @@
+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",
+          "ruby",
+          "php",
+          "go",
+          "rust",
+          "csharp",
+          "swift",
+        ])
+        .default("typescript")
+        .describe("Target language for the practice project"),
+      functionName: tool.schema.string().optional().describe("Entry function name (default: solve)"),
+      requirements: tool.schema.array(tool.schema.string()).default([]).describe("Testable requirements"),
+      edgeCases: tool.schema.array(tool.schema.string()).default([]),
+      starterCode: tool.schema.string().optional().describe("Optional starter implementation"),
+      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.languageName} (${result.runtime})`,
+        `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 });
+      }
+    },
+  };
+};