Skip to content

docs: seed AGENTS.md #184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
caffeine-ci-bot wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: seed AGENTS.md #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# AGENTS.md

`motoko` is a Node.js/browser library that compiles and runs Motoko smart contracts by wrapping the Motoko compiler (`moc`).

## Commands

- Build: `npm run build` (removes `lib/`, then compiles TypeScript with `tsc -p .`).
- Test: `npm test` (Jest via `ts-jest`).
- Format: `prettier --write <files>` (config in `.prettierrc`; enforced on commit).
- Size check: `npm run size-limit`.
- Regenerate compiler artifacts: `npm run generate -- <moc_version> <core_version>` (see below).

Node 22.x and 24.x are the versions exercised in CI. Install deps with `npm ci`.

## Layout (non-obvious)

- `src/` — TypeScript source; compiled output goes to `lib/`.
- `versions/latest/` — bundled minified `moc` compiler builds.
- `packages/latest/` — bundled Motoko core package (`core.json`).
- `contrib/generated/` — generated data (e.g. `errorCodes.json`).
- `utils/generate.js` — script that produces the bundled compiler, core package, and error codes.
- `contrib/` — editor/tooling integrations (highlight.js, Monaco, snippets).
- `index.js` / `interpreter.js` — entry points re-exporting from `lib/`.

## Conventions & gotchas

- Never hand-edit generated content: `lib/` (build output, gitignored), `versions/latest/`, `packages/latest/`, and `contrib/generated/`. Update these only via `npm run generate`.
- `motoko-src/` is a transient clone created during generation and is gitignored; do not commit it.
- Prettier settings are enforced: single quotes, semicolons, 4-space tabs, trailing commas. `lib/generated` is excluded from formatting.
- A Husky `pre-commit` hook runs `npm run precommit` (`lint-staged`), which formats staged JS/TS in `lib/`, `contrib/`, and `utils/`.
- `.npmrc` sets `min-release-age=7`, delaying adoption of newly published dependency versions.
- Publishing is automated: pushing a changed `version` in `package.json` to `main` triggers an npm publish, so bump the version deliberately.
- The `generate` script expects a checkout of the Motoko compiler repo, located via the `MOTOKO_REPO` environment variable (or auto-detects the latest release if version args are omitted).
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
See @AGENTS.md
Loading