philcoinhigh/Phil-tools

Open-source community tools for Phil, a systems language where architecture is executable and implementation is replaceable.
> Unofficial. This project is not part of, or endorsed by, the Phil project or its authors. Phil's own checker and documents are the authority on the language. Where these tools disagree with Phil, Phil is right and the disagreement is a bug here (please open an issue).
## Projects
| Project | What it is | Folder |
| Phil for VS Code | Editor extension: highlighting, live syntax errors with codes and quick fixes, hovers, outline, snippets, formatting | vscode/ |
| Phil Playground | Web app to write, run, replay and bug-hunt Phil programs, with examples and puzzles. Also runs Phil's own philc compiler, built to WebAssembly (philc/) | playground/ |
| Learn Phil | A course of fifteen short lessons with code you run and fix in the page | site/ |
| Phil OTC desk | An escrow desk and a two-listing order book, written in Phil. Simulation only: no real tokens move | otc/ |
| Hacks Phil would have stopped | Four well-known losses, each reduced to the shape of the mistake and refused in the page, with sources | core/src/sim/hacks.ts |
| Contract library | Vesting, a 2-of-3 treasury, an auction and a bonding-curve launch, written in Phil. Simulation only | contracts/ |
| What changed in Phil | A day-by-day record of what landed in the Phil repository, counted from its git history and refreshed daily | changelog/ |
| Compiler fuzzer | Generates programs and runs Phil's own compiler on them daily, looking for crashes, hangs and wrong answers | fuzz/ |
| Conformance report | Every test program in the Phil repository, run through these tools once a day | conformance/ |
| Phil core | The shared checker and experimental simulator, plus the command-line checker and the MCP server for AI assistants | core/ |
Each folder has its own README. The site at has a home page that links to the playground, the course and the OTC desk.
They live in one repository because they all use the same lexer and parser, written from Phil's normative grammar grammar/phase1-surface.ebnf; a grammar fix lands in every tool at once.
## Quick start
Requires Node.js 18 or newer.
sh
npm install
npm run build # extension, CLI, MCP server and playground
npm test # typecheck, simulator examples, designer, playground and extension tests
### Check a file
sh
node out/cli.js path/to/file.phil # file:line:col: error PHIL-P007: ...
node out/cli.js --json path/to/file.phil # machine-readable, includes quick-fix edits
node out/cli.js --format path/to/file.phil # print the re-indented file
Exit status is 0 with no errors, 1 with syntax errors, 2 on usage errors.
### Playground
npm run build writes the site to docs/: the home page at docs/index.html, the playground at docs/playground/, the course at docs/learn/, the OTC desk at docs/otc/, the hacks page at docs/hacks/, the contract library at docs/library/ the changelog at docs/changelog/ and the conformance report at docs/conformance/. Each page is self-contained. See playground/README.md. Open it in a browser, or serve the docs/ folder with GitHub Pages (repository Settings → Pages → Deploy from a branch → main / docs).