|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | + |
| 5 | +- Source: `src/` (entry: `src/index.ts`). Submodules: `commands/` (CLI subcommands), `components/` (Ink/React UI), `ui/` (top-level TUI), `mcp/` (MCP helpers), `config/`. |
| 6 | +- Build output: `dist/` (Node ESM, published via `bin` as `mstudio` and `missingstudio`). |
| 7 | +- Tests: colocated as `**/*.{test,spec}.ts(x)` inside `src/`. |
| 8 | +- Assets: `assets/` (images). Repo config under `.github/`, `.husky/`, `.changeset/`. |
| 9 | + |
| 10 | +## Build, Test, and Development Commands |
| 11 | + |
| 12 | +- `npm run dev`: Start locally with `tsx` (watches `src/`). |
| 13 | +- `npm run build`: TypeScript compile to `dist/`. |
| 14 | +- `npm start`: Build then run `dist/index.js`. |
| 15 | +- `npm test` / `npm run test:watch`: Run Vitest once / in watch mode. |
| 16 | +- `npm run typecheck`: TS type checking without emit. |
| 17 | +- `npm run format` / `format:fix`: Check / write Prettier formatting. |
| 18 | +- `npm run ci`: Formatting check + tests (used in CI). |
| 19 | + |
| 20 | +Example local run: |
| 21 | + |
| 22 | +``` |
| 23 | +npm install |
| 24 | +npm run dev |
| 25 | +# or: npm start |
| 26 | +``` |
| 27 | + |
| 28 | +## Coding Style & Naming Conventions |
| 29 | + |
| 30 | +- Language: TypeScript (ESM). Indent 2 spaces; semicolons; trailing commas; `printWidth: 80` (enforced by Prettier). |
| 31 | +- Filenames: kebab-case (`mcp-list.tsx`); React components in PascalCase exports (`AsciiLogo`). |
| 32 | +- Functions/variables: camelCase; types/interfaces: PascalCase. |
| 33 | +- Do not import from `dist/`; import via relative TS paths. |
| 34 | + |
| 35 | +## Testing Guidelines |
| 36 | + |
| 37 | +- Framework: Vitest with globals and Node env (`vitest.config.ts`). |
| 38 | +- Place tests next to source: `foo.test.ts(x)`. |
| 39 | +- Useful commands: `npm test` (CI), `npm run test:watch` (local). |
| 40 | +- Coverage is collected (v8) and emitted to `coverage/`; keep meaningful coverage for new code. |
| 41 | + |
| 42 | +## Commit & Pull Request Guidelines |
| 43 | + |
| 44 | +- Conventional Commits enforced by commitlint (Husky hooks run format + commitlint). |
| 45 | +- Examples: `feat(cli): add mcp list`, `fix(ui): handle empty state`, `chore: bump deps`. |
| 46 | +- PRs: include summary, motivation, linked issues, and CLI/TUI screenshots when visual output changes. Ensure `npm run ci` passes. |
| 47 | + |
| 48 | +## Security & Configuration Tips |
| 49 | + |
| 50 | +- Configuration: `.mstudio.json` defines MCP servers; avoid committing secrets. Environment variables via `.env` (loaded by `dotenv`). |
| 51 | +- Do not commit build artifacts or generated files outside `dist/`. |
0 commit comments