Skip to content

AGENTS.md

Latest commit

 

History

History
46 lines (32 loc) · 4.44 KB

AGENTS.md

File metadata and controls

46 lines (32 loc) · 4.44 KB
Raw

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

Hatch — project guide

Hatch is a single-user web app that teaches Python from zero to advanced practical Python. Real Python runs in the browser (Pyodide, in a module Web Worker). It is not a quiz app, not LeetCode and not an AI tutor.

Commands (npm only)

  • npm run dev — syncs assets, compiles content (strict: fails while any unit is unfinished), starts on :2034. While authoring, use HATCH_PREVIEW=1 npm run content && npx next dev -p 2034: preview mode leaves out units whose lessons are not all written yet.
  • npm run content / content:check / content:verify — compile, validate (schema, concept graph, prerequisite leaks, terminology, XP), and execute every solution/invalid sample through the real Python checker. HATCH_PARTIAL=1 ... --only <unit-id> validates one unit.
  • npm run typecheck, npm run lint, npm test (Vitest), npm run test:e2e (Playwright; reuses a server on :2034).
  • HATCH_E2E_UNITS=u01,u02 npx playwright test walkthrough plays whole lessons through the UI with their reference solutions.

Architecture (single source of truth)

  • python/hatch/ is the ONLY implementation of running, checking, AST feature analysis and error shaping. Browser: loaded into Pyodide by public/hatch-worker.js via python/hatch/bridge.py. Node (content verification, tests): python3 -m hatch.cli through src/curriculum/python.ts. Never re-implement checks in TypeScript.
  • content/ is YAML: course.yaml (tracks), achievements.yaml, units/<id>/unit.yaml (concept graph, features, terms, pitfalls) + one file per lesson. content/AUTHORING.md is the authoring spec. scripts/build-content.ts compiles to public/curriculum/ and src/generated/outline.json. Do not hand-edit generated files.
  • src/curriculum/ schema (zod), loader, graph (feature ownership, prerequisite-leak detection), validators, execution verifier.
  • src/engine/ pure logic with tests: XP ledger (idempotent), evidence-based mastery + spaced review, progress, next-action resolver, achievements, review sessions. No React, no storage.
  • src/store/ zustand store + persistence.ts (zod-validated localStorage, backups, never silent about failures).
  • src/runtime/ worker client, session (terminal state), run.ts (run in terminal), explain.ts (friendly error explanations).
  • src/components/lesson/workspace.tsx is the lesson/review orchestrator; step-views.tsx the step renderers.

Non-negotiable product rules

  • Teach before testing; one major idea per lesson; the app, not the learner, picks the order.
  • Validation is behavioural (run the program, scripted stdin, files, mocks) plus AST rules. Never match exact source text. Never hardcode outputs.
  • Errors: friendly explanation first (per-unit errorStyle), raw traceback always available; code is never erased on failure.
  • Mastery only rises through evidence (doing), never by reading. XP is idempotent per source.
  • No fake features: unsupported things (threads, real network, a real terminal) are said plainly in lessons.

Runtime notes

  • Needs cross-origin isolation (COOP/COEP set in next.config.ts) for SharedArrayBuffer: blocking input() and Stop use Atomics.
  • Pyodide 314 requires a MODULE worker (new Worker(url, { type: "module" }), import from /pyodide/pyodide.mjs).
  • asyncio.run in the live editor uses JSPI (callPromising). Without JSPI, python/hatch/live.py rewrites module-level asyncio.run(x) into await x; hidden checks that call asyncio.run themselves (expr/custom) are not supported there, so async lessons check stdout of the learner's whole program instead.
  • AST rules in a check apply to the entry file only. For multi-file projects, test structure with fixtures (e.g. an h.py helper that parses the module with ast) via custom tests.
  • Shell is zsh: quote globs in commands (--include='*.ts').