Development

Local setup

mikan requires Node.js >=24.15.0.

git clone https://github.com/geminixiang/mikan.git
cd mikan
npm install --ignore-scripts
npm run build

npm install without --ignore-scripts runs the repository’s Husky prepare hook. Use it when you want local commit hooks.

Repository layout

Path	Contents
src/	TypeScript source; each subdirectory has its own README.md describing its files
src/test/	The Vitest suite. .config/vitest.config.ts includes only src/test/**/*.test.ts
src/content/docs/	This documentation site (Starlight), plus the ja/, zh-cn/, and zh-tw/ locales
src/tsconfig.build.json	The build’s TypeScript project; the root tsconfig.json covers editor tooling
.config/	Tool configuration: Astro, Vitest (unit and E2E), oxlint, oxfmt
deploy/	Deployment assets: pm2/, docker/, and examples/ (embedder, bridges)
e2e/	Real-platform end-to-end suites, excluded from npm test
docs/adr/	Architecture decision records
scripts/	Maintenance and verification scripts invoked from npm scripts

Checks

npm run dev                  # TypeScript build in watch mode
npm test                     # unit/integration tests (Vitest)
npm run test:coverage        # test coverage report
npm run lint                 # oxlint
npm run fmt:check            # oxfmt check; npm run fmt fixes files
npm run build                # clean dist/, then type check + emit
npm run knip                 # dependency and export usage
npm run docs:build           # production documentation build
npm run docs:dev             # local documentation server
npm run docs:preview         # preview the built site after docs:build

Every script passes its config explicitly (for example vitest --run --config .config/vitest.config.ts), so the commands behave the same from any working directory.

Pass test file paths through to Vitest for a focused run:

npm test -- src/test/office-layout.test.ts src/test/workspace-projection.test.ts

Run the smallest relevant check while developing, then run lint, format check, tests, and build before a pull request.

Docker-backed office check

npm run test:office:docker

This one is not part of npm test: it needs a working Docker daemon. It creates two office directories and mounts them into real containers to prove an office cannot read outside its own mount, including through symlinks. Set MIKAN_OFFICE_TEST_IMAGE to use an image other than alpine:3.21.

Local runtime

Use a separate state directory so development does not overwrite a production instance:

HOME="$HOME/mikan-dev" ./dist/main.js onboard
HOME="$HOME/mikan-dev" ./dist/main.js --sandbox=host /path/to/workspace

At least one complete platform credential set is still required for normal bot mode.

Conversation directories in that workspace are named by office key, not by raw platform id. HOME="$HOME/mikan-dev" ./dist/main.js office list prints the registry — which platform and raw conversation id each office belongs to — plus any migration still pending.

End-to-end tests

The E2E suites under e2e/ call real platform APIs and are excluded from npm test (they use .config/vitest.e2e.config.ts, which matches e2e/**/*.e2e.ts and runs single-forked):

npm run test:e2e          # all configured platforms
npm run test:e2e:slack    # Slack only

Slack E2E requires SLACK_QA_USER_TOKEN, SLACK_QA_CHANNEL_ID, and SLACK_QA_BOT_USER_ID in a dedicated test workspace. SLACK_QA_WORKING_DIR and SLACK_QA_EVENTS_DIR override the workspace and events directory the suite watches; both default under .workspace/ in the repo. See the Slack QA test plan for setup and safety guidance.