Files
alexm e092cb029c
Build, test, deploy / site (push) Failing after 15m13s
Initial commit
2026-11-12 22:24:02 -05:00

7.8 KiB

AGENTS.md

Instructions for coding agents (and people) changing Programming+. Read this first, then the README for what the app is and where things are. When this file and a task's instructions disagree, the task wins; say so in your summary.

Build, test, and the gate

The engine core (the languages, translators, Mojo checker and interpreter, prover, fuzzer, machine model and the Mojo corpus) is pplus-core, the git submodule core/, with its own rules in core/AGENTS.md. This file is for the site.

pixi run test       # build core, then the site, then every test of the site
pixi run core-test  # core's own tests, at the pinned commit

Without pixi (a sandbox with only Node and Python):

npm install && npm test
(cd core && node --test tests/*.test.mjs && python3 scripts/mojo/corpus.py status --strict)

Finish every change with the gate green, both commands. The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green.

The site's suite takes under a minute. While iterating, build and run one file: npm run build && node --test tests/state.test.mjs.

Hard rules

  1. A change to what programs mean belongs in core. A translator, the checker, the interpreter, the prover, the fuzzer, the machine model, the catalog's problems, the Mojo corpus: change them in pplus-core under its rules (its own commit, its own gate), then move the core pointer here in a commit that says what it brings. Never edit core/ from a site change without that. The site imports core only as #core/<path>.js (the import map in index.html, imports in package.json), from its built core/dist/.
  2. Do not edit generated files by hand. quarto/_extensions/pplus/pplus-views.css comes from styles.css, pplus-hw.css and course/*.css beside it from styles/course/, and syntax/mojo.xml from core's core/library/syntax/mojo.xml (pixi run quarto-css; a test fails while they are out of date, so run it after changing a rule the views use). Core's generated files are listed in its AGENTS.md.
  3. Never claim Mojo compiles, runs, or prints something without the real compiler's answer. Mojo is pinned to 1.2.0 by core. What the app shows about Mojo comes from core's checker and interpreter and from godbolt's answers (stored in core/library/mojo/golden/, or asked live by Compile & run); the site never invents a verdict, and every Mojo construct written into the app must pass checkMojo.
  4. Never show "proved" for something that is not a proof. The badges and verdicts are in core/docs/trust.md; the site shows what core decided and does not soften or upgrade it.
  5. No new dependencies. TypeScript is the only npm package. There is no bundler, no framework, and no npm runtime dependency: CodeMirror, the one library the page runs, is vendored as one built module (src/vendor/), rebuilt only by scripts/vendor/codemirror.sh. tests/tasks.test.mjs holds package.json to that.
  6. You have no network in most sandboxes. Godbolt (Compile & run) needs one, and so do core's network tasks. Never fake their results; leave those steps to the owner and list them.
  7. Keep the workspace working while you change it. Code panes are always the CodeMirror editor (Editor in src/ui/editor.ts, over the vendored src/vendor/codemirror.js), never a <textarea>; tests/editor.test.mjs checks it. Keep the workspace's parts as they are unless the task changes them: the pane tabs over one editor, the stepper docked under the editor, the side column (the inspect panel, whose first tab is the Run view), and the dock; in the Hardware area, the code on the left and the arrangeable board on the right. Restyle or rearrange them only when asked, and after any UI change open the app (pixi run dev) and check that the editor has line numbers and highlighting, the stepper steps, and the styles loaded.

Conventions

  • Commands are pixi tasks. Name them as pixi run <task> in docs, comments, and messages. A new command is a task in pixi.toml with a description and a row in the README's Commands table; tests/tasks.test.mjs fails otherwise, and also fails on any pixi run <name> that names no task. package.json keeps only build, watch, check, dev, test (what CI uses).
  • Docs. The README is the front door: keep it short. Put behavior in docs/app.md, deployment in docs/deploy.md, and the Quarto extension in quarto/README.md. Exercises, the Mojo corpus, the engines and the prover's soundness are core's documents (core/docs/). Update the document a change belongs in, in the same commit.
  • Tests run against dist/ with no DOM. Logic about programs belongs in core; the site's own DOM-free logic (src/core/, src/quarto/) is tested here. A test that needs a piece of work uses a Session (src/core/session.ts), which extends core's Workspace. The views in src/ui/views/ also run outside a browser, under the small document of src/quarto/dom.ts, when the Quarto extension renders them: a view may use the selectors that document knows (compound selectors and the descendant combinator) and must not need layout to produce its markup. When a test needs localStorage, install a fake on globalThis and remove it in finally, as tests/state.test.mjs does. For a UI change, write a short manual check list in the commit message.
  • TypeScript. Strict mode, ES modules, imports with the .js suffix (from './state.js'). Indent like the file you are editing (some files use two spaces, some four).
  • Stable ids. Diagnostic ids (matho-refused, reserved-name, ...) and reference section ids are asserted by tests and linked from guides. Change one only on purpose, and update every test and link that names it.
  • Saved state. PlayState in src/core/state.ts is what share links, localStorage, and .pplus.json files hold, and normalize() reads it. A new field goes into normalize(); a field the student edits goes into EDITS (it drives editedFrom() and editsFingerprint()).
  • Writing. User-facing copy is US English (color, behavior, optimized, labeled). Plain sentences; say what a thing does, not how good it is.

Adding things

To add Do
A catalog problem, a probe, a stress program, a corpus or prover regression, a language, a library routine in core (a library routine in pplus-library, core's submodule library/) (core/AGENTS.md), then move the core pointer here; a problem's area comes from defaultAreaFor in src/core/catalog.ts
A command a task in pixi.toml and a row in the README's Commands table
A Quarto shortcode a function in the table quarto/_extensions/pplus/pplus.lua returns, a row in SHORTCODES (src/quarto/shortcodes.ts) and in scripts/check-pages.mjs, a sample in the gallery (src/ui/quarto.ts) and a use in quarto/example/; a rendered view is a case of renderStatic (src/quarto/render.ts); a view of the machine is a name in HW_NAMES (src/quarto/machine.ts), HW_VIEWS in pplus.lua and HW_VIEWS in scripts/check-pages.mjs

Delivering work

  • One logical change per commit, with a message that says what changed and why: the problem first, then what each part of the change does.
  • When the owner asks for patches, export them with git format-patch -o patches/ <base> (the patches/ folder is ignored by git) and do not paste whole files into chat. If the tree you were given has no .git, run git init and commit it unchanged first, so the patches have a base.
  • End with a summary: what you changed, the gate's result, the core commit the site is pinned to if it moved, anything you could not verify (network steps, manual UI checks), and anything you noticed but left alone.