maket AGENTS.md

Maket

Visual design tool for Codex: compose HTML/CSS documents with live preview, manage assets and brand chartes, export PDF, and prepare Gmail drafts. The MCP server uses Streamable HTTP at POST /mcp.

Working contract

• Treat the current checkout and executable contracts as the source of truth. Inspect before changing; preserve unrelated work and persistent data.
• Keep one coherent contract per change. Complete migrations in the same diff: update every entry point, remove the obsolete path, and do not add deprecation shims.
• Persistence types contain persistent state only. Transient state belongs in a dedicated service; packages/server/src/services/pending.ts is the reference pattern.
• Test user-visible workflows at their public boundary. Keep lower-level tests only when they protect a distinct validation, security, wire-format, or deterministic domain contract.

Commands and quality gates

npm run dev       # server --watch + Vite HMR; normal development path
npm run dev:watch # server --watch + Vite build --watch into public/
npm run quality   # lint + smell review + typecheck + tests + version alignment
npm run lint:fix  # Biome autofix

Node >=22. The server must already be running before Codex connects; the human normally owns that process, so do not start a second development server.

• npm run quality is the required local gate before review and again after addressing findings.
• The pre-commit hook runs staged Biome fixes, typecheck, and tests in parallel. It is a commit guard, not a substitute for quality.
• Tests are co-located (foo.ts + foo.test.ts). Database tests use createSQLiteStore(":memory:"); never use the filesystem.
• Coverage configuration lives in packages/server/vitest.config.ts and packages/client/vitest.config.ts.
• Run commands that require npm registry access, global installation, loopback listeners, or Chromium outside the sandbox from the outset. In particular, request escalation directly for npm install, npm install -g, npm run test:package, package-install smoke tests, npm run quality, and maket start/maket doctor; do not first retry these known-incompatible commands inside the sandbox. Use an isolated writable cache such as npm_config_cache=/private/tmp/maket-npm-cache instead of the user npm cache when it contains root-owned files.